@umriss-ui/dashboard 0.0.0-stage → 0.40.1

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import { HTMLAttributes } from 'react';
+import { ReactNode } from 'react';
+
+/** What `useDashboard` takes. */
+export declare interface DashboardOptions {
+    /** The arrangement the application gives a reader who has none of their own. */
+    defaultView: DashboardView;
+    /** The reader's kept arrangement, read once when the hook first runs; a
+     different value on a later render is ignored, as React ignores a changed
+     `defaultValue`. To go to another, call `setView`.
+     @default the `defaultView` */
+    initialView?: DashboardView;
+    /** Whether the reader may edit. Without it no bar is drawn and the mode cannot be entered.
+     @default true */
+    allowEdit?: boolean;
+    /** Called once per "Done" that changed something, with the whole arrangement. Not called by `setView`. */
+    onViewChange?: (view: DashboardView) => void;
+    /** Called with `true` when a draft opens and with `false` when it closes - to warn before navigation. */
+    onDraftChange?: (open: boolean) => void;
+}
+
+/** What `useDashboard` hands back. */
+export declare interface DashboardParts {
+    /** The dashboard. One per `useDashboard`. */
+    Dashboard: (props: DashboardProps) => ReactNode;
+    /** Declares a widget type inside `Dashboard`. */
+    WidgetType: typeof WidgetType;
+    /** The arrangement in view: the draft while the mode is on. */
+    view: DashboardView;
+    /** Goes to a whole arrangement. Not reported. */
+    setView: (view: DashboardView) => void;
+    /** Whether the editing mode is on. */
+    editing: boolean;
+    /** Enters the editing mode. Does nothing where editing is not allowed. */
+    edit: () => void;
+    /** Leaves the mode, keeps the changes and reports them once if there are any. */
+    done: () => void;
+    /** Opens the catalogue. Does nothing outside the editing mode. */
+    catalogue: () => void;
+    /** Leaves the mode and puts the arrangement back as it was before `edit`. */
+    cancel: () => void;
+    /** Goes one step back in the draft. Does nothing at the first. */
+    undo: () => void;
+    /** Goes one step forward again. Does nothing at the last. */
+    redo: () => void;
+    /** Steps to the `defaultView`; `undo` brings the arrangement back. */
+    reset: () => void;
+}
+
+/** The props of `Dashboard`. */
+export declare interface DashboardProps extends HTMLAttributes<HTMLDivElement> {
+    /** The `WidgetType`s of this dashboard. */
+    children?: ReactNode;
+    /** The `name`s of the widget types the catalogue lists.
+     @default every declared type */
+    catalogue?: ReadonlyArray<string>;
+}
+
+/** The arrangement of a dashboard: which widgets, in what order, at which
+ sizes, with which options. An object, so that more can join it later. */
+export declare interface DashboardView {
+    /** The widgets, in the order they are drawn and read. */
+    widgets: ReadonlyArray<DashboardWidget>;
+}
+
+/** One widget in a view. */
+export declare interface DashboardWidget {
+    /** Unique within the view. */
+    id: string;
+    /** The `name` of the widget type it is an instance of. */
+    type: string;
+    /** One of the sizes its type offers. */
+    size: WidgetSize;
+    /** The type's own options, typed through the hook. */
+    options: unknown;
+}
+
+/** The options of the heading widget type. */
+export declare interface HeadingOptions {
+    /** The title across the full width. */
+    text: string;
+}
+
+/** The built-in heading widget type, to put inside `Dashboard` when the
+ application wants readers to divide their dashboard: one size, `full`, one
+ row, its text as its options, drawn as a title without a card. */
+export declare function HeadingType(): null;
+
+/** The room a size takes on the twelve columns, in columns and rows. */
+export declare interface SizeSpan {
+    /** Columns of twelve. */
+    columns: number;
+    /** Rows of the fixed row unit. */
+    rows: number;
+}
+
+/** Declares a dashboard: hands back `Dashboard`, `WidgetType`, the view in
+ view, `setView` and the editing actions. */
+export declare function useDashboard({ defaultView, initialView, allowEdit, onViewChange, onDraftChange }: DashboardOptions): DashboardParts;
+
+/** What a widget's content is told. */
+export declare interface WidgetContent<Options> {
+    /** The size the widget stands at. */
+    size: WidgetSize;
+    /** The widget's options. */
+    options: Options;
+}
+
+/** What a type's form is given. */
+export declare interface WidgetFormProps<Options> {
+    /** The widget's current options. */
+    options: Options;
+    /** Replaces the options; one step of the draft. */
+    change: (options: Options) => void;
+}
+
+/** The closed set of names a widget's size comes from. A widget type offers a
+ subset of them. */
+export declare type WidgetSize = "small" | "medium" | "wide" | "tall" | "large" | "full";
+
+/** Declares one widget type inside a `Dashboard`. It draws nothing itself: the
+ dashboard reads its props. The options type is inferred from `defaultOptions`. */
+export declare function WidgetType<Options>(props: WidgetTypeProps<Options>): null;
+
+/** The props of `WidgetType`. */
+export declare interface WidgetTypeProps<Options> {
+    /** The name a view refers to this type by. Unique within the dashboard. */
+    name: string;
+    /** The type's name for a reader, and the title of its frame unless `title` says otherwise. */
+    label: string;
+    /** One sentence on what the type shows. */
+    sentence: string;
+    /** The sizes the type offers, each with the columns (of twelve) and rows it takes. */
+    sizes: Partial<Record<WidgetSize, SizeSpan>>;
+    /** The size a new widget of this type starts at. One of `sizes`. */
+    start: WidgetSize;
+    /** The options a new widget starts with. Their type is the options type of `title` and of the content. */
+    defaultOptions: Options;
+    /** The title of a frame as a function of its options; the `label` without it. */
+    title?: (options: NoInfer<Options>) => string;
+    /** The form for the options, opened from the widget's menu. Without it the menu has no options entry. */
+    form?: (props: WidgetFormProps<NoInfer<Options>>) => ReactNode;
+    /** The content, as a function of the size and the options. */
+    children: (content: WidgetContent<NoInfer<Options>>) => ReactNode;
+}
+
+export { }