nexus-shell 0.2.8 → 0.2.9

package/README.md

@@ -138,6 +138,9 @@ shell's own frame and keep every registration working.
 | `useGraphLayout` | Auto layout engines, with a freeform escape for hand placement |
 | `layeredLayout` | Layered tree layout in four directions; handles cycles |
 | `gridLayout` | Uniform grid, ignoring edges |
+| `PropertyPanel` | Inspector for the current selection, with mixed-value editing |
+| `TextField` … `StaticField` | Nine composable property fields, usable on their own |
+| `FieldShell` | The label / description / error frame, for fields of your own |
 | `UserProfile` | Avatar and identity widget |
 
 ## Theming

package/dist/components/graph/GraphEdge.d.ts

@@ -58,7 +58,9 @@ export declare const edgePath: (from: IPoint, to: IPoint, fromPort: GraphPort, r
  */
 export declare const GraphEdge: ({ edge, source, target, routing, selected, arrow, onSelect, onContextMenu, className, }: GraphEdgeProps) => import("react/jsx-runtime").JSX.Element;
 export interface GraphEdgeLayerProps {
+    /** The edges to draw. Anything SVG works — this is just the surface. */
     children?: React.ReactNode;
+    /** Extra classes merged onto the `<svg>` element. */
     className?: string;
 }
 /**

package/dist/components/properties/FieldShell.d.ts

@@ -0,0 +1,65 @@
+import { ReactNode } from 'react';
+
+/** Props every field in this family accepts. */
+export interface FieldProps<T> {
+    /** Label shown above the control. */
+    label: string;
+    /** Current value. `undefined` renders as empty. */
+    value: T | undefined;
+    /** Called with the new value. */
+    onChange?: (value: T) => void;
+    /** One line under the label explaining the property. */
+    description?: string;
+    /**
+     * Selected subjects hold different values. The control shows a placeholder
+     * instead of a value, and editing applies to all of them.
+     */
+    mixed?: boolean;
+    /** Render read-only. */
+    disabled?: boolean;
+    /** Validation message, shown in the destructive colour. */
+    error?: string;
+    /** Extra classes merged onto the field wrapper. */
+    className?: string;
+}
+export interface FieldShellProps {
+    /** Label shown above the control, or beside it when `inline`. */
+    label: string;
+    /** Associates the label with the control. */
+    htmlFor?: string;
+    /** One line under the control explaining the property. Hidden while `error` is set. */
+    description?: string;
+    /** Validation message, shown in the destructive colour in place of the description. */
+    error?: string;
+    /** Selected subjects hold different values — renders the *Mixed* marker beside the label. */
+    mixed?: boolean;
+    /** The control itself. */
+    children: ReactNode;
+    /**
+     * Render the label beside the control rather than above. Suits checkboxes,
+     * where a label on its own line reads as a heading for nothing.
+     */
+    inline?: boolean;
+    /** Extra classes merged onto the field wrapper. */
+    className?: string;
+}
+/**
+ * The label, description and error frame shared by every property field.
+ *
+ * Exported so a bespoke field looks like the built-in ones without copying
+ * their markup — which is exactly what went wrong in the examples this family
+ * replaces, where the same label styling was pasted into three inspectors.
+ *
+ * @example
+ * ```tsx
+ * <FieldShell label="Opacity" description="0 to 1" htmlFor="opacity">
+ *   <MyCustomSlider id="opacity" />
+ * </FieldShell>
+ * ```
+ */
+export declare const FieldShell: ({ label, htmlFor, description, error, mixed, children, inline, className, }: FieldShellProps) => import("react/jsx-runtime").JSX.Element;
+/** Shared control styling, so every field lines up. */
+export declare const CONTROL_CLASS: string;
+export declare const borderClass: (error?: string) => "border-border" | "border-destructive";
+/** A stable id per field, so labels associate without the caller supplying one. */
+export declare const fieldId: (label: string, suffix?: string) => string;

package/dist/components/properties/PropertyPanel.d.ts

@@ -0,0 +1,132 @@
+import { ReactNode } from 'react';
+import { IPropertyAccessor, IPropertyValue } from '../../lib/properties';
+
+/**
+ * One editable property.
+ *
+ * `type` names a renderer in the field registry. The built-ins are listed in
+ * {@link BUILT_IN_FIELD_TYPES}, and any string works once you register a
+ * renderer for it.
+ */
+export interface IPropertyField<S = unknown> extends IPropertyAccessor<S> {
+    /** Label shown above the control. */
+    label: string;
+    /** Field type. Defaults to `"text"`. */
+    type?: string;
+    /** One line under the label explaining the property. */
+    description?: string;
+    /** Group heading this field sits under. Ungrouped fields come first. */
+    group?: string;
+    /** Render read-only. */
+    disabled?: boolean;
+    /**
+     * Hide the field for the current selection — a property that only applies to
+     * some node kinds, say. Receives the selected subjects.
+     */
+    when?: (subjects: S[]) => boolean;
+    /** Return a message to show the field as invalid. */
+    validate?: (value: unknown, subjects: S[]) => string | undefined;
+    /**
+     * Anything the renderer needs: `options` for a select, `rows` for a text
+     * area, `unit` for a number, or whatever your own field type expects.
+     */
+    props?: Record<string, unknown>;
+}
+/** What a field renderer receives. */
+export interface FieldRendererProps<S = unknown> {
+    field: IPropertyField<S>;
+    /** The shared value across the selection, and whether subjects disagree. */
+    state: IPropertyValue;
+    /** Apply a value to every selected subject. */
+    onChange: (value: unknown) => void;
+    /** The selected subjects, for a renderer that needs more than one value. */
+    subjects: S[];
+    /** Validation message, if `validate` returned one. */
+    error?: string;
+}
+/** Renders one field. Register your own to extend the panel. */
+export type FieldRenderer<S = unknown> = (props: FieldRendererProps<S>) => ReactNode;
+/**
+ * The field types the panel understands out of the box.
+ *
+ * Spread it to add your own, or replace an entry to change how a type renders
+ * everywhere:
+ *
+ * ```tsx
+ * <PropertyPanel
+ *   fieldTypes={{ ...BUILT_IN_FIELD_TYPES, latlong: LatLongField }}
+ * />
+ * ```
+ */
+export declare const BUILT_IN_FIELD_TYPES: Record<string, FieldRenderer<any>>;
+export interface PropertyPanelProps<S = unknown> {
+    /**
+     * The selected subjects. Zero renders the empty state, one edits normally,
+     * several edit together with a mixed indicator where values differ.
+     */
+    subjects: S[];
+    /** The properties to show. */
+    fields: IPropertyField<S>[];
+    /**
+     * Called with every subject updated. The panel produces new copies and never
+     * mutates, so this is the whole edit — apply it to your state.
+     */
+    onChange?: (updated: S[], field: IPropertyField<S>, value: unknown) => void;
+    /**
+     * Field renderers by type. Defaults to {@link BUILT_IN_FIELD_TYPES}; spread
+     * it to add your own without losing the built-ins.
+     */
+    fieldTypes?: Record<string, FieldRenderer<S>>;
+    /** Shown when nothing is selected. */
+    emptyState?: ReactNode;
+    /**
+     * Heading above the fields. Receives the selection, so it can read
+     * "3 nodes selected" as easily as a name.
+     */
+    title?: ReactNode | ((subjects: S[]) => ReactNode);
+    /** Group headings render in this order. Unlisted groups follow, in first-seen order. */
+    groupOrder?: string[];
+    /** Extra classes merged onto the root element. */
+    className?: string;
+    /** Accessible label for the region. Defaults to `"Properties"`. */
+    'aria-label'?: string;
+}
+/**
+ * An inspector: the properties of whatever is selected, as editable fields.
+ *
+ * Give it the selection and a list of field descriptors. It reads each
+ * property across every selected subject, renders the matching field, and hands
+ * back new copies on edit — it holds no state and mutates nothing.
+ *
+ * Three selection states are handled for you:
+ *
+ * - **none** — the empty state.
+ * - **one** — ordinary editing.
+ * - **several** — shared values edit together; where subjects disagree the
+ *   field shows *Mixed* rather than one subject's value, and editing applies to
+ *   all of them.
+ *
+ * That last case is the one hand-rolled inspectors usually skip, and skipping
+ * it is how a multi-selection edit silently flattens data.
+ *
+ * Every field is also exported on its own — reach for `TextField` and friends
+ * when a property needs bespoke arrangement, and use `FieldShell` to make a
+ * custom control look like the rest.
+ *
+ * @example
+ * ```tsx
+ * <PropertyPanel
+ *   subjects={selectedNodes}
+ *   title={(nodes) => nodes.length > 1 ? `${nodes.length} nodes` : 'Node'}
+ *   fields={[
+ *     { key: 'data.label', label: 'Label' },
+ *     { key: 'kind', label: 'Type', type: 'select',
+ *       props: { options: [{ value: 'idea', label: 'Idea' }] } },
+ *     { key: 'data.notes', label: 'Notes', type: 'textarea', group: 'Detail' },
+ *     { key: 'data.tags', label: 'Tags', type: 'tags', group: 'Detail' },
+ *   ]}
+ *   onChange={(updated) => setNodes(merge(nodes, updated))}
+ * />
+ * ```
+ */
+export declare const PropertyPanel: <S>({ subjects, fields, onChange, fieldTypes, emptyState, title, groupOrder, className, "aria-label": ariaLabel, }: PropertyPanelProps<S>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/properties/fields.d.ts

@@ -0,0 +1,101 @@
+import { ReactNode } from 'react';
+import { FieldProps } from './FieldShell';
+
+export interface TextFieldProps extends FieldProps<string> {
+    /** Hint shown in an empty control. Replaced by the mixed placeholder when `mixed`. */
+    placeholder?: string;
+    /** Input type, for the browser's own affordances. Defaults to `"text"`. */
+    inputType?: 'text' | 'url' | 'email' | 'tel' | 'password';
+}
+/** A single-line text property. */
+export declare const TextField: ({ label, value, onChange, description, mixed, disabled, error, placeholder, inputType, className, }: TextFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface TextAreaFieldProps extends FieldProps<string> {
+    /** Hint shown in an empty control. Replaced by the mixed placeholder when `mixed`. */
+    placeholder?: string;
+    /** Visible rows. Defaults to `4`. */
+    rows?: number;
+}
+/** A multi-line text property — notes, descriptions, evidence. */
+export declare const TextAreaField: ({ label, value, onChange, description, mixed, disabled, error, placeholder, rows, className, }: TextAreaFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface ISelectOption {
+    value: string;
+    label: string;
+    /** Render unselectable — an unavailable choice you still want visible. */
+    disabled?: boolean;
+}
+export interface SelectFieldProps extends FieldProps<string> {
+    /** The choices, in the order they should appear. */
+    options: ISelectOption[];
+    /** Shown as the first, unselected entry. */
+    placeholder?: string;
+}
+/** A choice from a fixed set. */
+export declare const SelectField: ({ label, value, onChange, description, mixed, disabled, error, options, placeholder, className, }: SelectFieldProps) => import("react/jsx-runtime").JSX.Element;
+export type CheckboxFieldProps = FieldProps<boolean>;
+/**
+ * A boolean property.
+ *
+ * When `mixed`, the box renders indeterminate — neither on nor off — which is
+ * the only honest state for a selection that disagrees.
+ */
+export declare const CheckboxField: ({ label, value, onChange, description, mixed, disabled, error, className, }: CheckboxFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface NumberFieldProps extends FieldProps<number> {
+    /** Lowest accepted value. Enforced by the browser, not by this component. */
+    min?: number;
+    /** Highest accepted value. Enforced by the browser, not by this component. */
+    max?: number;
+    /** Increment for the spinner and arrow keys. */
+    step?: number;
+    /** Unit shown inside the control's trailing edge, e.g. `"px"`. */
+    unit?: string;
+    /** Hint shown in an empty control. Replaced by the mixed placeholder when `mixed`. */
+    placeholder?: string;
+}
+/** A numeric property. */
+export declare const NumberField: ({ label, value, onChange, description, mixed, disabled, error, min, max, step, unit, placeholder, className, }: NumberFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface ColorFieldProps extends FieldProps<string> {
+    /** Show the hex value in an editable text box beside the swatch. Default `true`. */
+    showValue?: boolean;
+}
+/** A colour property, as a swatch plus an editable hex value. */
+export declare const ColorField: ({ label, value, onChange, description, mixed, disabled, error, showValue, className, }: ColorFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface DateFieldProps extends FieldProps<string> {
+    /** Include a time component. Defaults to `false`. */
+    withTime?: boolean;
+    /** Earliest selectable date, in the same ISO form as `value`. */
+    min?: string;
+    /** Latest selectable date, in the same ISO form as `value`. */
+    max?: string;
+}
+/**
+ * A date property, as an ISO `yyyy-mm-dd` string (or `yyyy-mm-ddThh:mm` with
+ * `withTime`). A string rather than a `Date` so it round-trips through JSON
+ * unchanged.
+ */
+export declare const DateField: ({ label, value, onChange, description, mixed, disabled, error, withTime, min, max, className, }: DateFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface TagFieldProps extends FieldProps<string[]> {
+    /** Hint shown in the draft box. Defaults to `"Add and press Enter"`. */
+    placeholder?: string;
+    /** Offer these as a datalist while typing. */
+    suggestions?: string[];
+}
+/**
+ * A list-of-strings property.
+ *
+ * Enter or the add button commits the draft; duplicates and blanks are
+ * rejected silently rather than with an error, since neither is a mistake worth
+ * interrupting for.
+ */
+export declare const TagField: ({ label, value, onChange, description, mixed, disabled, error, placeholder, suggestions, className, }: TagFieldProps) => import("react/jsx-runtime").JSX.Element;
+export interface StaticFieldProps extends Omit<FieldProps<ReactNode>, 'onChange'> {
+    /** Render in a monospaced face — ids, hashes, coordinates. */
+    mono?: boolean;
+}
+/**
+ * A read-only property: an id, a timestamp, a computed total.
+ *
+ * Present because inspectors are full of values worth showing and not worth
+ * editing, and a disabled text input reads as "you may not edit this yet"
+ * rather than "this is derived".
+ */
+export declare const StaticField: ({ label, value, description, mixed, mono, className, }: StaticFieldProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/properties/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Property editing.
+ *
+ * An inspector is one of the things every application with a canvas, a tree or
+ * a selection ends up needing, and one of the things most often hand-rolled
+ * three times over. This family covers it at two levels: composable fields you
+ * arrange yourself, and a descriptor-driven panel built on them.
+ *
+ * Nothing here is graph-specific — the subjects can be nodes, edges, tree
+ * items, rows, or an application's settings object.
+ */
+export { FieldShell, CONTROL_CLASS, borderClass, fieldId, type FieldShellProps, type FieldProps, } from './FieldShell';
+export { TextField, TextAreaField, SelectField, CheckboxField, NumberField, ColorField, DateField, TagField, StaticField, type TextFieldProps, type TextAreaFieldProps, type SelectFieldProps, type CheckboxFieldProps, type NumberFieldProps, type ColorFieldProps, type DateFieldProps, type TagFieldProps, type StaticFieldProps, type ISelectOption, } from './fields';
+export { PropertyPanel, BUILT_IN_FIELD_TYPES, type PropertyPanelProps, type IPropertyField, type FieldRenderer, type FieldRendererProps, } from './PropertyPanel';

package/dist/index.d.ts

@@ -59,5 +59,7 @@ export { UserProfile, type UserProfileProps, type IUserProfile, type IUserProfil
 export * from './components/graph';
 export { BUILT_IN_LAYOUTS, gridLayout, layeredLayout, type GraphLayout, type GridLayoutOptions, type LayeredLayoutOptions, type LayoutDirection, } from './lib/layout';
 export { DEFAULT_NODE_SIZE, IDENTITY_VIEWPORT, clampScale, edgesOf, findNeighbour, fitViewport, graphBounds, isConnected, nextId, nodeRect, placeRelativeTo, portPoint, rectCenter, removeNode, resolvePorts, toGraphSpace, toScreenSpace, unionRect, viewportRect, centerOn, zoomAt, type Direction, type GraphPort, type IGraphEdge, type IGraphNode, type IPoint, type IRect, type IViewport, } from './lib/graph';
+export * from './components/properties';
+export { getPath, setPath, readValue, readValues, writeValue, writeValues, type IPropertyAccessor, type IPropertyValue, } from './lib/properties';
 export { cn } from './lib/cn';
 export { BUNDLED_THEMES, BUNDLED_THEME_CLASSES, themeClass, type IBundledTheme, type BundledThemeId, } from './lib/themes';

package/dist/lib/properties.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Reading and writing property values across one or many subjects.
+ *
+ * The awkward parts of a property panel are not the inputs — they are knowing
+ * what to show when several things are selected and their values disagree, and
+ * writing a nested value back without mutating anything. Both live here, as
+ * pure functions, so they can be tested without rendering.
+ */
+/** A value shared by every selected subject, or a marker that they differ. */
+export interface IPropertyValue<T = unknown> {
+    /** The common value, or `undefined` when subjects disagree or none are selected. */
+    value: T | undefined;
+    /**
+     * Subjects hold different values for this property.
+     *
+     * A field showing `mixed` must not display one subject's value as if it were
+     * everyone's — that is how a multi-selection edit silently flattens data.
+     */
+    mixed: boolean;
+}
+/**
+ * Read a dot-separated path, e.g. `"data.label"`.
+ *
+ * Returns `undefined` for a missing path rather than throwing, because a
+ * property panel routinely renders objects that don't have every field yet.
+ */
+export declare const getPath: (subject: unknown, path: string) => unknown;
+/**
+ * Return a copy of `subject` with `path` set to `value`.
+ *
+ * Every object along the path is cloned, so the original is untouched and React
+ * sees a new reference at each level it needs to. Missing intermediate objects
+ * are created.
+ */
+export declare const setPath: <T>(subject: T, path: string, value: unknown) => T;
+/** How a property is read from and written to a subject. */
+export interface IPropertyAccessor<S = unknown, V = unknown> {
+    /** Dot path, used for both reading and writing unless overridden. */
+    key: string;
+    /** Custom read. Defaults to `getPath(subject, key)`. */
+    get?: (subject: S) => V;
+    /** Custom write, returning a new subject. Defaults to `setPath`. */
+    set?: (subject: S, value: V) => S;
+}
+/** Read a property from one subject, honouring a custom accessor. */
+export declare const readValue: <S, V>(subject: S, accessor: IPropertyAccessor<S, V>) => V;
+/** Write a property to one subject, honouring a custom accessor. */
+export declare const writeValue: <S, V>(subject: S, accessor: IPropertyAccessor<S, V>, value: V) => S;
+/**
+ * Read a property across a selection.
+ *
+ * With one subject this is just its value. With several, it is the shared value
+ * — or `mixed`, if they disagree. With none, it is empty and not mixed.
+ *
+ * Comparison is by `Object.is`, so two structurally equal objects at the same
+ * path read as mixed. That is deliberate: a panel cannot know whether deep
+ * equality is meaningful for an arbitrary payload, and claiming agreement it
+ * hasn't verified is the more damaging error.
+ */
+export declare const readValues: <S, V>(subjects: S[], accessor: IPropertyAccessor<S, V>) => IPropertyValue<V>;
+/**
+ * Apply a value to every subject, returning new copies.
+ *
+ * Subjects that already hold the value are returned unchanged by identity, so
+ * an edit across a large selection only invalidates what actually moved.
+ */
+export declare const writeValues: <S, V>(subjects: S[], accessor: IPropertyAccessor<S, V>, value: V) => S[];