@crewlethq/ui 0.18.0 → 0.19.0

package/README.md

@@ -41,15 +41,16 @@ import { Button } from '@crewlethq/ui/Button';  // 8 KB of CSS, not 182 KB
 | Area | Components |
 | ---- | ---------- |
 | Actions | `Button` and `ButtonLink` (variants `primary`, `secondary`, `outline`, `ghost`, `accent`, `danger`; sizes `small`, `medium`, `large`; shapes `square`, `pill`), `IconButton`, `Menu`, `Link`, `Copyable`, `CopyButton`, `DownloadButton`, `Kbd` |
-| Content and text | `Text` (the eight registers and `inherit`), `Prose`, `Document` and `DocumentTitle`, `Highlight`, `InlineCode`, `List` and `ListItem`, `DescriptionList`, `Timeline`, `RelativeTime` |
+| Content and text | `Text` (the eight registers and `inherit`), `Prose`, `Document` and `DocumentTitle`, `Highlight`, `InlineCode`, `List` and `ListItem`, `DescriptionList`, `Timeline`, `RelativeTime`, `Note`, `Divider` |
 | Forms | `Input`, `Textarea`, `Label`, `FormField`, `FormRow`, `Checkbox`, `CheckboxGroup`, `ConfirmField`, `Select`, `Tag`, `TagsInput`, `DateTimePicker`, `TimeWindowPicker`, `ImageUpload`, `CharacterPicker`, `HuePicker`, `AvatarPicker`, `FactList`, `ChoiceList`, `Composer`, `MarkdownEditor` |
-| Data display | `DataTable`, `CopyableCell`, `Table`, `StatCard`, `Meter`, `SegmentedMeter`, `Stepper`, `PricingCard`, `Avatar`, `AvatarStack`, `EntityChip`, `CodeBlock`, `QrCode`, `ObjectHeader`, `FactLine`, `SetByLine`, `Skeleton`, `Eyebrow` |
+| Data display | `DataTable`, `CopyableCell`, `Table`, `StatCard`, `Meter`, `SegmentedMeter`, `Stepper`, `PricingCard`, `Avatar`, `AvatarStack`, `EntityChip`, `CodeBlock`, `QrCode`, `ObjectHeader`, `FactLine`, `SetByLine`, `Skeleton`, `Eyebrow`, `StatGroup`, `PinTile`, `IconTile` |
 | List screens | `DataView`, and its parts on their own: `DataViewToolbar`, `FilterAxisBar`, `FilterAxisChip`, plus the filter model (`filterDefsFromColumns`, `applyColumnFilters`, `filterPredicate`, `blankFilterValue`) |
 | Feedback and overlays | `Callout`, `Toaster`, `Modal` (with `variant="sheet"`), `ConfirmModal`, `CommandPalette`, `Tooltip`, `Popover`, `Announcer` |
 | Charts | `Legend`, `BarList`, `StackedBar`, `StackedColumns`, `ActivityStrip`, `TimeSeries`, `Sparkline`, the reading layer they share (`ChartTooltip`, `useChartHover`), and the ramp (`DATA_COLORS`, `DATA_COLOR_OTHER`, `dataColor`) |
 | Marks | `Count`, `StatusDot`, `EmptyValue`, `VisuallyHidden` |
 | Hooks and seams | `useModalLayer`, `usePopupLayer`, `LayerHost`, `useListbox`, `useOptionKeys`, `useHighlightRest` and `HIGHLIGHT_REST_MS`, `useClipboard`, `useDownload`, `downloadText`, `safeFilename`, `useOutcome`, `useAnnouncer`, `useNow`, `formatRelative`, `HeadingLevelProvider`, `cx`, the node hues (`NODE_HUES`, `NODE_HUE_NAMES`, `isNodeHue`) |
 | Layout | `Container`, `Section`, `Card`, `Tabs`, `Accordion`, `Disclosure`, `Outline` (with `useActiveHeading` and `scrollToHeading`), `TreeGrid` |
+| Arranging a page | `ArrangeBoard`, `ArrangeFrame` (with `useGridResize`), `ArrangeGroup`, `ArrangeList`, and the reorder hooks under them (`useReorder`, `useReorderLists`, `moveKey`) |
 | Application shell | `AppShell` with `AppShell.Rail`, `AppShell.Topbar`, `AppShell.AccountRow` and `useAppShell`, `AuthLayout`, `SidebarNav` and `NavItem`, `BrandLockup`, `SearchTrigger`, `PageHeader`, `Toolbar`, `Stack`, `Inline`, `Spacer`, `AutoGrid`, `ErrorBoundary`, `useShortcut`, `useFullscreen` |
 | Preferences | `ThemeToggle`, `ThemeSwitcher`, `DensitySwitcher`, `ThemeGallery`, `ThemeSwatch`, `useThemePreference`, `useDensityPreference`, `useSystemTheme`, `resolveTheme`, `applyStoredPreferences`, and the framework-free `applyTheme`, `applyPalette`, `applyDensity` with `THEME_PREFERENCES`, `DENSITY_PREFERENCES` and their guards |
 | Artifacts | `SandboxedFrame`, `LinkInterstitial` and `openExternal`, `VersionTimeline`, `ShareDialog` with the role ladder (`ARTIFACT_ROLES`, `SHAREABLE_ROLES`, `roleAtLeast`), `PrincipalPicker`, `Principal` and `PrincipalAvatar`, `ArtifactCard` and `ArtifactKindGlyph`, `AccessDeniedCard`, and `FrameProtocol` (the wire between a host page and an embedded artifact, with no React in it) |
@@ -201,6 +202,22 @@ places:
 - A surface that pans or zooms dispatches `LAYER_REPOSITION_EVENT` on its host
   when the content beneath it moves, and every panel anchored inside follows.
 
+## Changes in 0.19.0
+
+0.19.0 adds what a page needs to be arranged by its reader: blocks they move, resize and group on a board, the layout pieces they add between them, and the tray those come from. The engine console's Home is built from it.
+
+**`useReorder` and `useReorderLists`** put items in order within one list or across several (a page and the groups on it), by drag, by keyboard and by command. The handle is a named control the arrow keys move from. Another list shows where a dragged item will land (`data-reorder-target`, with `data-reorder-line` saying whether the mark runs beside the item or across it) and the move is made on the drop. Every move is announced and glides unless the reader asked for reduced motion. `accepts` refuses a drop (a group inside a group), `moveTo` moves an item to another list by command, and `moveKey` is exported.
+
+**`ArrangeBoard`** is the ground an arranged page stands on: a fine hatch at rest, and the page's columns as lanes while a block is carried or resized. Its hatch is the new **`--color-border-hatch` token** in `@crewlethq/tokens`, measured in every theme, and a `Note` on the board shows it through its paper. **`ArrangeFrame`** is one block on it: layout only at rest; while editing, the block is its own move handle, one accent ring is drawn over its edge on hover or focus, and its toolbar (an `actions` slot and Remove) and resize grips sit on that ring. **`useGridResize`** snaps a resize to twelve columns and 16px rows, from the corner or, for width alone, the edge, by pointer and by keyboard. **`ArrangeGroup`** is a titled band that holds blocks and folds away, its title edited in place, and **`ArrangeList`** is a list a reader orders and switches on and off.
+
+**`Note`** is words on coloured paper, in any node hue or plain. **`Divider`** is a rule between parts of a page, with an optional label. **`PinTile`** is something a reader pinned, with the one or two facts that make opening it unnecessary. **`IconTile`** is a glyph on a hue-tinted square, what a choice in a catalog is told apart by before its name is read.
+
+**`Modal` takes `onBack` and `backLabel`**, a step back that leads the head for a surface reached from another, and **`backdrop="clear"`**, for a sheet that edits the page beside it. **`StatGroup` takes `flush`**, for a row of figures inside another card. **`HuePicker` takes `none`**, which offers no hue first under the name you give it ("Plain") and then reports `"none"`.
+
+**A `Card` with `asChild` holds its child's own content.** With no header slots it used to draw the child again inside its own clone: a link inside a link, a button inside a button.
+
+What to change: nothing, unless code extends `HuePickerProps` as an interface; it is a type now, so intersect it instead. Everything else is new.
+
 ## Changes in 0.18.0
 
 0.18.0 adds the pieces the engine dashboard's Artifacts workspace is built from: the frame an artifact runs in, its versions, who it is shared with, and the card and refusal that stand for it elsewhere; the editable sheet; and the marks that show who else is in an artifact.

package/dist/AccessDeniedCard/index.js

@@ -1,6 +1,6 @@
-export { ACCESS_DENIED_REASONS, AccessDeniedCard } from '../chunk-LFZ45HV2.js';
+export { ACCESS_DENIED_REASONS, AccessDeniedCard } from '../chunk-G3EEUNZQ.js';
 import '../chunk-RA2ULG6H.js';
-import '../chunk-EG6NYWVK.js';
+import '../chunk-YZCJ63JF.js';
 import '../chunk-AV2DXAEL.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-BHHIIK3M.js';

package/dist/AppShell/index.js

@@ -1,7 +1,7 @@
-export { AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellToggle, AppShellTopbar, useAppShell } from '../chunk-OYOQU7O5.js';
+export { AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellToggle, AppShellTopbar, useAppShell } from '../chunk-EDGCPVVD.js';
 import '../chunk-IG75YMUN.js';
-import '../chunk-4FQT6ZAY.js';
 import '../chunk-HMPFGIWM.js';
 import '../chunk-R25RGPUB.js';
+import '../chunk-4FQT6ZAY.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/ArrangeBoard/ArrangeBoard.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface ArrangeBoardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Whether the page is being arranged. */
+    editing: boolean;
+    /**
+     * Columns of the page grid the blocks snap to, shown as lanes while a block
+     * is carried or resized. The grid's gap is read from
+     * `--crewlet-arrange-board-gap` (one `--spacing-4` unless set).
+     */
+    columns?: number | undefined;
+    children: ReactNode;
+}
+/**
+ * The ground a page's blocks stand on while it is arranged.
+ *
+ * A FINE HATCH SAYS "ARRANGING" AT REST. While editing, the blocks keep their
+ * own look and light up only when hovered, so something has to say the page
+ * is in a different mode before anything is touched. The ground under them
+ * does it: diagonal hairlines, the drafting mark for a surface under
+ * construction, with no frame of its own, so it adds no border to the borders
+ * already on the page. Most of it sits under the blocks, and in the gaps
+ * between them it reads as a cutting mat.
+ *
+ * THE COLUMNS SHOW WHILE A BLOCK MOVES. Carried or resized, the page's columns
+ * appear as lanes on the ground, as wide as the grid exactly, so a lane is
+ * the column a block will snap to; at rest they are gone.
+ *
+ * IT TAKES NO WIDTH FROM THE BLOCKS. The ground reaches a step past the blocks
+ * on each side rather than padding them inward, so entering editing never
+ * reflows a card to a narrower width.
+ */
+export declare function ArrangeBoard({ editing, columns, className, style, children, ...rest }: ArrangeBoardProps): import("react").JSX.Element;

package/dist/ArrangeBoard/index.d.ts

@@ -0,0 +1,3 @@
+import './ArrangeBoard.css';
+export { ArrangeBoard } from './ArrangeBoard.js';
+export type { ArrangeBoardProps } from './ArrangeBoard.js';

package/dist/ArrangeBoard/index.js

@@ -0,0 +1,2 @@
+export { ArrangeBoard } from '../chunk-QO7QEQKV.js';
+import '../chunk-ODEQTPFM.js';

package/dist/ArrangeBoard-MQE35P6Z.css

@@ -0,0 +1,80 @@
+/*
+ * ArrangeBoard: the ground under a page being arranged. Two layers, both
+ * under every block (the board is its own stacking context, so they sit above
+ * its background and below its content): the hatch on `::after`, and the
+ * column lanes on `::before`, shown only while a block is carried or resized.
+ */
+
+.crewlet-arrange-board {
+  --crewlet-arrange-board-gap: var(--spacing-4);
+  /* The hatch, as one value: the ground below and the notes standing on it
+     draw the same lines. */
+  --crewlet-arrange-board-hatch: repeating-linear-gradient(
+    -45deg,
+    var(--color-border-hatch) 0 1px,
+    transparent 1px var(--spacing-2)
+  );
+
+  min-width: 0;
+}
+
+.crewlet-arrange-board.is-editing {
+  position: relative;
+  isolation: isolate;
+  margin-inline: calc(var(--spacing-3) * -1);
+  padding: var(--spacing-5) var(--spacing-3);
+  border-radius: var(--radius-xl);
+}
+
+/* Room to land below the last block while one is carried out of a group:
+   a page made only of groups otherwise has no bare stretch of its own. */
+.crewlet-arrange-board.is-editing:has(.crewlet-arrange-group__body [data-reorder='dragging']) {
+  padding-bottom: var(--spacing-11);
+}
+
+/* The hatch: its own ink, the strong hairline's held back to 60%, one
+   diagonal every half step, so the cards standing on it stay the loudest
+   thing on the page. */
+.crewlet-arrange-board.is-editing::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background: var(--crewlet-arrange-board-hatch);
+  pointer-events: none;
+}
+
+/* A note is an annotation on the ground, not a card on it: while the page is
+   arranged its paper shows the hatch through, inside a group as well, where
+   the group's own surface hides the ground. */
+.crewlet-arrange-board.is-editing .crewlet-note {
+  background: var(--crewlet-arrange-board-hatch), var(--crewlet-note-paper);
+}
+
+/* The lanes: one tile per column and its gap, as wide as the grid, so the
+   twelfth tile's gap falls outside the board and is not drawn. */
+.crewlet-arrange-board.is-editing::before {
+  content: '';
+  position: absolute;
+  inset: 0 var(--spacing-3);
+  background: linear-gradient(
+      to right,
+      var(--color-brand-accent-soft) 0 calc(100% - var(--crewlet-arrange-board-gap)),
+      transparent 0
+    )
+    0 0 / calc((100% + var(--crewlet-arrange-board-gap)) / var(--crewlet-arrange-board-columns)) 100%
+    repeat-x;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity var(--motion-duration-base) var(--motion-easing-default);
+}
+.crewlet-arrange-board.is-editing:has([data-reorder='dragging'], .crewlet-arrange-frame.is-resizing)::before {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-arrange-board.is-editing::before {
+    transition: none;
+  }
+}

package/dist/ArrangeFrame/ArrangeFrame.d.ts

@@ -0,0 +1,82 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import type { ReorderHandleProps } from '../Reorder/index.js';
+import { type GridSize } from './useGridResize.js';
+export interface ArrangeFrameResize {
+    minColumns?: number | undefined;
+    maxColumns?: number | undefined;
+    minRows?: number | undefined;
+    maxRows?: number | undefined;
+    /** False for a block whose height is always its content's: width only. */
+    vertical?: boolean | undefined;
+    onResize: (next: GridSize) => void;
+}
+export interface ArrangeFrameProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** What the block is called: every control's name. */
+    name: string;
+    /** Whether the page is being arranged. Off, the frame draws its child only. */
+    editing: boolean;
+    /** Columns of the page grid the block spans. */
+    columns: number;
+    /** Rows tall, or null for its content's height. */
+    rows?: number | null | undefined;
+    /** One row's height in pixels. */
+    rowHeight?: number | undefined;
+    /** The handle's props from `useReorder`, spread on the block itself; left out, it does not move. */
+    handle?: ReorderHandleProps | undefined;
+    /** Resize by the corner or the edge; left out, the block keeps its size. */
+    resize?: ArrangeFrameResize | undefined;
+    /** Controls of the block's own on its toolbar: settings, a menu. */
+    actions?: ReactNode;
+    /** Take the block off the page; left out, it cannot be removed. */
+    onRemove?: (() => void) | undefined;
+    /** Why the block cannot be removed, said on the button that would. */
+    fixed?: string | undefined;
+    /**
+     * A block that holds other blocks (a group). Its content stays operable
+     * while arranging, because the blocks inside are arranged in place and
+     * each makes its own content inert; a press on its fields types rather
+     * than moves it.
+     */
+    container?: boolean | undefined;
+    /**
+     * A block with no surface of its own (a heading, a divider): its ring is
+     * drawn a step outside it, so the words are not pressed against it.
+     */
+    bare?: boolean | undefined;
+    /** The block whose settings are open: ringed until they close. */
+    selected?: boolean | undefined;
+    /** Drawn once with the accent, for a block the reader just added. */
+    fresh?: boolean | undefined;
+    children: ReactNode;
+}
+/**
+ * One block of a page the reader is arranging: moved by its grip or its
+ * surface, sized from its corner or its edge, taken off from its toolbar.
+ *
+ * ONE BOUNDARY, THE BLOCK'S OWN. A card already draws its edge, and a second
+ * outline around it read as two borders. At rest a block being arranged looks
+ * exactly as it does on the page. Hovered or focused, ONE accent ring is drawn
+ * over its own edge (on the innermost block only, so a card inside a group
+ * does not light the group as well), with its toolbar and its resize handle.
+ *
+ * THE CHROME NEVER COVERS THE BLOCK'S CONTROLS. The toolbar sits on the
+ * block's top edge, half outside it, clear of a card's own header links; the
+ * corner bracket follows the card's own radius.
+ *
+ * TWO HANDLES FOR TWO RESIZES. A block that may be sized both ways carries a
+ * corner bracket; one whose height is always its content's (a heading, a
+ * figure, a group) carries a grip on its right edge, the handle of a column
+ * splitter, so the handle says which way it moves before it is touched.
+ *
+ * THE GRID SHOWS WHILE RESIZING, measured from the grid the block sits on
+ * (the page's, or a group's), so the columns drawn are the ones it snaps to.
+ *
+ * THE BLOCK IS ITS OWN HANDLE. A block's content is inert while arranging,
+ * so a press on it can mean nothing but "move this": the whole block is the
+ * drag source, and focused it moves with the arrow keys, so the toolbar
+ * carries no grip. A container (a group) is moved the same way, by its header
+ * or its edge, except from a field, where a press types or selects.
+ *
+ * A FIXED HEIGHT SCROLLS ITS CONTENT rather than cutting it off.
+ */
+export declare const ArrangeFrame: import("react").ForwardRefExoticComponent<ArrangeFrameProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/ArrangeFrame/index.d.ts

@@ -0,0 +1,5 @@
+import './ArrangeFrame.css';
+export { ArrangeFrame } from './ArrangeFrame.js';
+export type { ArrangeFrameProps, ArrangeFrameResize } from './ArrangeFrame.js';
+export { useGridResize } from './useGridResize.js';
+export type { GridResizeHandleProps, GridResizeOptions, GridSize } from './useGridResize.js';

package/dist/ArrangeFrame/index.js

@@ -0,0 +1,5 @@
+export { ArrangeFrame, useGridResize } from '../chunk-DEJHAOC5.js';
+import '../chunk-RSAQOKH3.js';
+import '../chunk-4FQT6ZAY.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/ArrangeFrame/useGridResize.d.ts

@@ -0,0 +1,66 @@
+import { type KeyboardEvent, type PointerEvent, type RefObject } from 'react';
+/** A block's size on a page grid: columns it spans, and rows tall or null for its content's height. */
+export interface GridSize {
+    columns: number;
+    rows: number | null;
+}
+export interface GridResizeOptions {
+    /** What the block is called, for the handle's name and the announcement. */
+    name: string;
+    size: GridSize;
+    /** One row's height in pixels: the step a height snaps to. */
+    rowHeight: number;
+    minColumns?: number | undefined;
+    /** Left out, the grid's own column count. */
+    maxColumns?: number | undefined;
+    minRows?: number | undefined;
+    maxRows?: number | undefined;
+    /** False for a block whose height is always its content's (a group): width only. */
+    vertical?: boolean | undefined;
+    /** A finished resize: a pointer released, a key pressed, or the height fitted. */
+    onResize: (next: GridSize) => void;
+}
+export interface GridResizeHandleProps {
+    'aria-label': string;
+    'aria-keyshortcuts': string;
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+    onPointerCancel: () => void;
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    onDoubleClick: () => void;
+}
+/**
+ * Where the grid's columns fall, measured from the block's own left edge, so
+ * a block can draw the guides of the grid it sits on (the page's, or a
+ * group's) while it is being resized.
+ */
+export interface GridGuides {
+    left: number;
+    width: number;
+    columns: number;
+    gap: number;
+}
+/**
+ * Resizing a block on a page grid by its corner, snapped to whole columns
+ * across and whole rows down, with the keyboard doing the same.
+ *
+ * SNAPPED AS IT MOVES. The block follows the pointer in steps of the grid it
+ * sits on, so what the reader sees while dragging is exactly where it will
+ * land; nothing reflows after the release. The release reports once, and
+ * Escape puts the block back.
+ *
+ * WIDTH ALONE LEAVES THE HEIGHT TO THE CONTENT. A block whose height fits its
+ * content keeps doing so until the pointer has moved down or up by half a
+ * row; a sideways drag is a width change and nothing else. A double press on
+ * the handle (or Enter) fits the height to the content again.
+ *
+ * THE ARROW KEYS ON THE HANDLE resize by one column or one row, and every
+ * change is said, because a corner that only a pointer can drag is a control
+ * nobody on a keyboard has.
+ */
+export declare function useGridResize(frame: RefObject<HTMLElement | null>, { name, size, rowHeight, minColumns, maxColumns, minRows, maxRows, vertical, onResize }: GridResizeOptions): {
+    live: GridSize | null;
+    guides: GridGuides | null;
+    handleProps: GridResizeHandleProps;
+};