[dome] TS boxes

ivette/src/dome/src/renderer/layout/boxes.js → ivette/src/dome/src/renderer/layout/boxes.tsx

@@ -3,10 +3,6 @@
 // --------------------------------------------------------------------------
 
 /**
-   @packageDocumentation
-   @module dome/layout/boxes
-   @description
-
    This modules offers several `<div>` containers with various
    predefined layout.
 
@@ -20,14 +16,14 @@
    then vertically by wrapping cells in rows.
 
    The various containers layout and extensibility is listed below:
-    - [[Hbox]] horizontal, fixed height
-    - [[Vbox]] vertical, fixed width
-    - [[Hpack]] horizontal, fixed dimensions
-    - [[Vpack]] vertical, fixed dimensions
-    - [[Hfill]] horizontal, extends in both directions
-    - [[Vfill]] vertical, extends in both directions
-    - [[Grid]] uses CSS grid columns, extends in both directions
-    - [[Scroll]] scrolls its content
+   - [[Hbox]] horizontal, fixed height
+   - [[Vbox]] vertical, fixed width
+   - [[Hpack]] horizontal, fixed dimensions
+   - [[Vpack]] vertical, fixed dimensions
+   - [[Hfill]] horizontal, extends in both directions
+   - [[Vfill]] vertical, extends in both directions
+   - [[Grid]] uses CSS grid columns, extends in both directions
+   - [[Scroll]] scrolls its content
 
    Inside a box, you may add `<Space/>` and `<Filler/>` to separate items.
    Inside a grid, you may also use `<Space/>` or an empty `<div/>` for empty cells.
@@ -35,21 +31,31 @@
    <strong>Warning:</strong> large elements will be clipped if they overflow.
    If you want to add scrolling capabilities to some item that does not manage overflow
    natively, place it inside a `<Scroll/>` sub-container.
-*/
+
+   @packageDocumentation
+   @module dome/layout/boxes
+ */
 
 import React from 'react';
 import * as Dome from 'dome';
-import { Title } from 'dome/controls/labels' ;
-import './style.css' ;
+import { Title } from 'dome/controls/labels';
+import './style.css';
 
 // --------------------------------------------------------------------------
 // --- Generic Box
 // --------------------------------------------------------------------------
 
-const makeBox = ( boxClasses, props, morestyle ) => {
-  const { children, className, style, ...others } = props ;
-  const allClasses = className ? boxClasses + ' ' + className : boxClasses ;
-  const allStyles = morestyle ? (style ? Object.assign( {}, style, morestyle ) : morestyle) : style ;
+/** Div properties that you can also use in boxes. */
+export type DivProps = React.HTMLAttributes<HTMLDivElement>;
+
+const makeBox = (
+  boxClasses: string,
+  props: DivProps,
+  morestyle?: React.CSSProperties,
+) => {
+  const { children, className, style, ...others } = props;
+  const allClasses = className ? boxClasses + ' ' + className : boxClasses;
+  const allStyles = morestyle ? (style ? Object.assign({}, style, morestyle) : morestyle) : style;
   return (
     <div className={allClasses} style={allStyles} {...others} >
       {children}
@@ -62,120 +68,109 @@ const makeBox = ( boxClasses, props, morestyle ) => {
 // --------------------------------------------------------------------------
 
 /**
-   @summary Horizontal box (extends horizontally, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements will be clipped if they overflow.
+   Horizontal box (extends horizontally, no overflow).
 */
-export const Hbox = (props) => makeBox( 'dome-xBoxes-hbox dome-xBoxes-box' , props );
+export const Hbox = (props: DivProps) => makeBox('dome-xBoxes-hbox dome-xBoxes-box', props);
 
 /**
-   @summary Vertical box (extends vertically, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements will be clipped if they overflow.
+   Vertical box (extends vertically, no overflow).
 */
-export const Vbox = (props) => makeBox( 'dome-xBoxes-vbox dome-xBoxes-box' , props );
+export const Vbox = (props: DivProps) => makeBox('dome-xBoxes-vbox dome-xBoxes-box', props);
 
 /**
-   @summary Compact Horizontal box (fixed dimensions, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements would be clipped if they overflow.
+   Compact Horizontal box (fixed dimensions, no overflow).
 */
-export const Hpack = (props) => makeBox( 'dome-xBoxes-hbox dome-xBoxes-pack' , props );
+export const Hpack = (props: DivProps) => makeBox('dome-xBoxes-hbox dome-xBoxes-pack', props);
 
 /**
-   @summary Compact Vertical box (fixed dimensions, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements will be clipped if they overflow.
+   Compact Vertical box (fixed dimensions, no overflow).
 */
-export const Vpack = (props) => makeBox( 'dome-xBoxes-vbox dome-xBoxes-pack' , props );
+export const Vpack = (props: DivProps) => makeBox('dome-xBoxes-vbox dome-xBoxes-pack', props);
 
 /**
-   @summary Horizontally filled box (fixed height, maximal width, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements will be clipped if they overflow.
+   Horizontally filled box (fixed height, maximal width, no overflow).
 */
-export const Hfill = (props) => makeBox( 'dome-xBoxes-hbox dome-xBoxes-fill' , props );
+export const Hfill = (props: DivProps) => makeBox('dome-xBoxes-hbox dome-xBoxes-fill', props);
 
 /**
-   @summary Vertically filled box (fixed width, maximal height, no overflow).
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
-   <strong>Warning:</strong> large elements will be clipped if they overflow.
+   Vertically filled box (fixed width, maximal height, no overflow).
 */
-export const Vfill = (props) => makeBox( 'dome-xBoxes-vbox dome-xBoxes-fill' , props );
+export const Vfill = (props: DivProps) => makeBox('dome-xBoxes-vbox dome-xBoxes-fill', props);
 
 // --------------------------------------------------------------------------
 // --- Scrolling & Spacing
 // --------------------------------------------------------------------------
 
 /**
-   @summary Scrolling container.
-   @property {object} [...props] - Extra properties passed to the `<div>` container
+   Scrolling container.
 */
-export const Scroll = (props) => makeBox( 'dome-xBoxes-scroll dome-container' , props );
+export const Scroll = (props: DivProps) => makeBox('dome-xBoxes-scroll dome-container', props);
 
 /**
-   @summary Rigid space between items in a box.
-   @property {object} [...props] - Extra properties passed to the `<div>` separator
+   Rigid space between items in a box.
 */
-export const Space = (props) => makeBox( 'dome-xBoxes-space' , props );
+export const Space = (props: DivProps) => makeBox('dome-xBoxes-space', props);
 
 /**
-   @summary Extensible space between items in a box.
-   @property {object} [...props] - Extra properties passed to the `<div>` separator
+   Extensible space between items in a box.
 */
-export const Filler = (props) => makeBox( 'dome-xBoxes-filler' , props );
+export const Filler = (props: DivProps) => makeBox('dome-xBoxes-filler', props);
 
 // --------------------------------------------------------------------------
 // --- Grids
 // --------------------------------------------------------------------------
 
+export interface GridProps extends DivProps { columns?: string; }
+
 /**
-   @summary Grid box container.
-   @property {string} [columns] - Grid column specifications
-   @property {object} [...props] - Extra properties passed to the `<div>` container
-   @description
+   Grid box container.
+
    Layout its children in a multi-column grid. Each column is specified by its
    width, following the CSS Grid Layout `grid-template-columns` property.
 
    The rows are populated with children from left-to-right, using one column at a time.
-   Items layout can be modified by adding CSS Grid Layout item properties.
+   Items layout can be modified by using CSS Grid Layout item properties.
 
    Example: `<Grid columns="25% auto auto"> ... </Grid>`
 */
-export const Grid = ({columns='auto',...props}) =>
-  makeBox( 'dome-xBoxes-grid', props , { gridTemplateColumns: columns });
+export const Grid = (props: GridProps) => {
+  const { columns, ...others } = props;
+  return makeBox('dome-xBoxes-grid', others, { gridTemplateColumns: columns });
+};
 
 // --------------------------------------------------------------------------
 // --- Folders
 // --------------------------------------------------------------------------
 
+export interface FolderProps {
+  /** Title bar label. */
+  label: string;
+  /** Title bar tooltip. */
+  title?: string;
+  /** Window settings key. */
+  settings?: string;
+  /** Default state (`false`). */
+  defaultUnfold?: boolean;
+  /** Contents left margin (in pixels, defaults to 18). */
+  indent?: number;
+  /** Children JSX elements. */
+  children: any;
+}
+
 /**
-   @summary Foldable Vpack box.
-   @property {string} label - box label
-   @property {string} [title] - box label tooltip
-   @property {string} [settings] - window setting to store the fold/unfold state
-   @property {boolean} [defaultUnfold] - initial state (default is `false`)
-   @property {React.Children} [children] - content of the vertical box
-   @description
-   A vertical `Vpack` box with a clickable head label to fold/unfold its content.
+   Foldable (vertical, packed) box.
+   The head label is clickable to fold/unfold its contents.
 */
-export const Folder =
-  ({ settings, defaultUnfold=false, indent=18, label, title, children }) =>
-{
-  const [ unfold , setUnfold ] = Dome.useState( settings, defaultUnfold );
-  const icon = unfold ? 'TRIANGLE.DOWN' : 'TRIANGLE.RIGHT' ;
-  const onClick = () => setUnfold( !unfold );
+export const Folder = (props: FolderProps) => {
+  const { settings, defaultUnfold = false, indent = 18, label, title, children } = props;
+  const [unfold, onClick] = Dome.useSwitch(settings, defaultUnfold);
+  const icon = unfold ? 'TRIANGLE.DOWN' : 'TRIANGLE.RIGHT';
+  const display = unfold ? 'none' : 'block';
   return (
     <Vpack>
       <Hpack onClick={onClick}><Title icon={icon} label={label} title={title} /></Hpack>
-      <Vpack style={{ marginLeft:indent }}>
-        { unfold && children }
+      <Vpack style={{ display, marginLeft: indent }}>
+        {children}
       </Vpack>
     </Vpack>
   );