@objectifthunes/whiteboard 0.3.0 → 0.5.0

package/README.md

@@ -63,11 +63,28 @@ Every component is driven by `--wb-*` CSS custom properties. Override on `:root`
 
 - **Canvas:** `WhiteboardShell`, `FloatingPanel`, `Minimap`, `ZoomBar`, `ConfirmDialog`, `PanelErrorBoundary`
 - **Store / hooks:** `useWhiteboardStore`, `useWhiteboardLayout`, `computeWhiteboardFit`, `computeWhiteboardRectFocus`, `usePanelRect`, `belowPanel`, `snapToWhiteboardGrid`, `WHITEBOARD_GRID`, `cn`
-- **Primitives:** `Button`, `ButtonRow`, `PanelCloseButton`, `ThemeToggle`, `OverlayIconButton`, `Field`, `Label`, `Input`, `Textarea`, `Select`, `CoordGrid`, `CoordInput`, `Alert`, `Pill`, `Chip`, `TagRow`, `LoadingState`, `GeneratingOverlay`, `EmptyState`, `Stack`, `Inline`, `TitleRow`, `SplitLayout`, `IconText`, `PageShell`, `PageCard`, `PageTitle`, `CardTitle`, `SectionTitle`, `SectionDescription`, `MutedText`, `ItemCard`, `ItemList`, `List`, `PickerCard`, `PickerGrid`, `ChoiceCard`, `ChoiceGroup`, `VerticalToolbar`, `AvatarBadge`, `CanvasStage`, `ImageThumb`, `PanelSection`, `PanelTitle`
+- **Primitives:** `Button`, `ButtonRow`, `PanelCloseButton`, `ThemeToggle`, `OverlayIconButton`, `Field`, `Label`, `Input`, `Textarea`, `Select`, `CoordGrid`, `CoordInput`, `Alert`, `Pill`, `Chip`, `TagRow`, `LoadingState`, `GeneratingOverlay`, `EmptyState`, `Stack`, `Inline`, `TitleRow`, `SplitLayout`, `IconText`, `PageShell`, `PageCard`, `PageTitle`, `CardTitle`, `SectionTitle`, `SectionDescription`, `MutedText`, `ItemCard`, `ItemList`, `List`, `PickerCard`, `PickerGrid`, `ChoiceCard`, `ChoiceGroup`, `VerticalToolbar`, `AvatarBadge`, `CanvasStage`, `ImageThumb`, `PanelSection`, `PanelTitle`, `Checkbox`, `Switch`, `Slider`, `NumberField`, `Toolbar`, `Surface`, `Tooltip`, `Kbd`, `Divider`
 - **Skeletons:** `Skeleton`, `LineSkeleton`, `TitleSkeleton`, `ButtonSkeleton`, `IconButtonSkeleton`, `InputSkeleton`, `SelectSkeleton`, `TextareaSkeleton`, `ChipSkeleton`, `ThumbSkeleton`, `AvatarSkeleton`, `CanvasSkeleton`, `PanelFormSkeleton`, `CardSkeleton`, `PickerGridSkeleton`, `ChoiceGroupSkeleton`
 
 See the live demo for the full prop reference and copy-pasteable examples per component.
 
+## New in 0.5
+
+- **`Draggable` / `DraggableSurface`** — screen-space dragging for overlay chrome, no `WhiteboardShell` required. Keep your CSS anchoring; the drag is a `translate()` delta on top, so layouts stay responsive. Drags from any non-interactive area, snaps to the whiteboard grid on release, honours the global `whiteboard-snap-now` event, persists per `id` in localStorage. Double-click resets one element; `resetDraggables()` resets all.
+- `Toolbar` reads slightly larger (roomier padding, `--wb-fs-md` buttons) — it's app chrome, not a panel row.
+
+## New in 0.4
+
+Battle-tested additions from building a real app on the kit:
+
+- **`Checkbox` / `Switch`** — labeled boolean rows; the input pins its own size so host globals can never stretch it.
+- **`Slider`** — label left, live readout right, themed range underneath. Returns numbers.
+- **`NumberField`** — labeled numeric input; clamps to min/max, never emits NaN.
+- **`Toolbar`** — horizontal sibling of `VerticalToolbar` for app-chrome bars (`position="top" | "bottom" | "static"`, `end` slot).
+- **`Surface`** — the plain floating overlay container (selection menus, legends, log panes) for overlays living outside a `WhiteboardShell`.
+- **`Tooltip`** — CSS-only, shows on hover and keyboard focus. `Kbd` for shortcut hints, `Divider` (h/v) for separation.
+- **Hardening** — `PickerCard` declares its own column layout (the global `button` style can no longer collapse it into a clipped row); native text/number inputs are now styled like `select` out of the box.
+
 ## Build size
 
 42 KB JS raw / ~10 KB gzip, single 30 KB CSS file. No runtime CSS-in-JS.

package/dist/index.d.ts

@@ -92,6 +92,20 @@ declare interface CardTitleProps extends TypographyProps {
     clamp?: boolean;
 }
 
+/**
+ * A labeled checkbox row. The input pins its own size and flex so host
+ * (or kit) globals like `input { flex: 1 }` can never stretch it across
+ * the row.
+ */
+export declare function Checkbox({ label, hint, className, ...props }: CheckboxProps): JSX_2.Element;
+
+declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /** Sentence-case text rendered next to the box. */
+    label?: ReactNode;
+    /** Muted addition after the label, e.g. "(dirty scans)". */
+    hint?: ReactNode;
+}
+
 export declare function Chip({ className, ...props }: ChipProps): JSX_2.Element;
 
 declare type ChipProps = HTMLAttributes<HTMLSpanElement>;
@@ -173,6 +187,47 @@ declare interface CoordInputProps extends Omit<InputHTMLAttributes<HTMLInputElem
     axis: string;
 }
 
+/** Hairline separator; vertical inside toolbars/inlines, horizontal in stacks. */
+export declare function Divider({ orientation, className, ...props }: DividerProps): JSX_2.Element;
+
+declare interface DividerProps extends HTMLAttributes<HTMLElement> {
+    orientation?: 'horizontal' | 'vertical';
+}
+
+/**
+ * Screen-space dragging for overlay chrome — toolbars, legends, log
+ * panes — WITHOUT a WhiteboardShell. Keep your CSS anchoring (top/right/
+ * bottom/left, even percentage centring on a parent): the drag is a
+ * translate() delta on top of it, so layouts stay responsive and reset
+ * is just "delta = 0".
+ *
+ * - drags from any non-interactive area (inputs, buttons, canvases keep
+ *   their own pointer behaviour)
+ * - snaps to WHITEBOARD_GRID on release; honours the global
+ *   `whiteboard-snap-now` event dispatched by ZoomBar
+ * - double-click an empty area to reset one element;
+ *   `resetDraggables()` resets them all
+ * - position persists per `id` in localStorage
+ */
+export declare function Draggable({ id, snap, persist, disabled, className, style, children, ...props }: DraggableProps): JSX_2.Element;
+
+declare interface DraggableProps extends HTMLAttributes<HTMLDivElement> {
+    /** Stable id — keys persistence and the reset registry. */
+    id: string;
+    /** Snap the offset to the whiteboard grid on release. Default true. */
+    snap?: boolean;
+    /** Remember the offset in localStorage. Default true. */
+    persist?: boolean;
+    disabled?: boolean;
+}
+
+/** A Surface you can drag — the overlay-panel workhorse. */
+export declare function DraggableSurface({ padding, className, ...props }: DraggableSurfaceProps): JSX_2.Element;
+
+declare interface DraggableSurfaceProps extends DraggableProps {
+    padding?: 'none' | 'sm' | 'md';
+}
+
 export declare function EmptyState({ title, description, action }: EmptyStateProps): JSX_2.Element;
 
 declare interface EmptyStateProps {
@@ -265,6 +320,9 @@ declare interface ItemListProps extends HTMLAttributes<HTMLElement> {
     as?: ElementType;
 }
 
+/** Keyboard-key chip for shortcut hints: <Kbd>esc</Kbd> <Kbd>⌫</Kbd>. */
+export declare function Kbd({ className, ...props }: HTMLAttributes<HTMLElement>): JSX_2.Element;
+
 export declare function Label({ className, ...props }: LabelProps): JSX_2.Element;
 
 declare type LabelProps = LabelHTMLAttributes<HTMLLabelElement>;
@@ -297,6 +355,20 @@ export declare function MutedText({ as, size, className, ...props }: TypographyP
 
 declare type MutedTextSize = 'xs' | 'sm' | 'md';
 
+/**
+ * Labeled numeric input. Values come back as numbers, clamped to
+ * [min, max] when provided; non-numeric keystrokes are ignored rather
+ * than emitted as NaN.
+ */
+export declare function NumberField({ label, hint, value, onChange, min, max, step, id, className, ...props }: NumberFieldProps): JSX_2.Element;
+
+declare interface NumberFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
+    label?: ReactNode;
+    hint?: ReactNode;
+    value: number;
+    onChange: (value: number) => void;
+}
+
 export declare function OverlayIconButton({ className, placement, onPointerDown, onWheel, onContextMenu, ...props }: OverlayIconButtonProps): JSX_2.Element;
 
 declare interface OverlayIconButtonProps extends Omit<ComponentProps<typeof Button>, 'variant' | 'iconOnly'> {
@@ -457,6 +529,9 @@ declare interface Props_6 {
     fallbackMessage?: string;
 }
 
+/** Snap every Draggable back to its anchored position (and clear persistence). */
+export declare function resetDraggables(): void;
+
 export declare function SectionDescription({ as, className, ...props }: TypographyProps): ReactElement<any, string | JSXElementConstructor<any>>;
 
 export declare function SectionTitle({ as, className, ...props }: TypographyProps): ReactElement<any, string | JSXElementConstructor<any>>;
@@ -476,6 +551,21 @@ declare interface SkeletonProps extends HTMLAttributes<HTMLElement> {
 
 declare type SkeletonRadius = 'sm' | 'md' | 'pill';
 
+/**
+ * The settings-panel slider pattern: label left, live readout right,
+ * range underneath. Numbers come back as numbers.
+ */
+export declare function Slider({ label, display, value, onChange, className, ...props }: SliderProps): JSX_2.Element;
+
+declare interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange'> {
+    /** Uppercase header on the left (rendered like a widget label). */
+    label?: ReactNode;
+    /** Right-aligned readout; defaults to the raw value. */
+    display?: ReactNode;
+    value: number;
+    onChange: (value: number) => void;
+}
+
 export declare function snapToWhiteboardGrid(value: number): number;
 
 /**
@@ -506,6 +596,22 @@ declare interface State {
     error: Error | null;
 }
 
+/**
+ * The plain floating surface: --wb-surface background, border, radius,
+ * soft shadow. For overlays that live OUTSIDE a WhiteboardShell —
+ * selection menus, legends, log panes — where FloatingPanel's canvas
+ * coupling would be wrong.
+ */
+export declare function Surface({ as, padding, className, ...props }: SurfaceProps): ReactElement<any, string | JSXElementConstructor<any>>;
+
+declare interface SurfaceProps extends HTMLAttributes<HTMLElement> {
+    as?: ElementType;
+    padding?: 'none' | 'sm' | 'md';
+}
+
+/** A labeled on/off switch — same API as Checkbox, slider visuals. */
+export declare function Switch({ label, hint, className, ...props }: CheckboxProps): JSX_2.Element;
+
 /**
  * A horizontal wrapping row for chips/tags/pills/small items.
  * Replaces `<div className="element-tags-row">`, `<div className="chip-row">`,
@@ -547,6 +653,32 @@ declare interface TitleRowProps extends HTMLAttributes<HTMLDivElement> {
 
 export declare function TitleSkeleton(props: HTMLAttributes<HTMLDivElement>): JSX_2.Element;
 
+/**
+ * Horizontal sibling of VerticalToolbar — same surface, same rhythm.
+ * The app-chrome bar: title, file chip, navigation, primary action.
+ */
+export declare function Toolbar({ children, end, position, className, ...props }: ToolbarProps): JSX_2.Element;
+
+declare interface ToolbarProps extends HTMLAttributes<HTMLElement> {
+    /** 'top' (fixed, centered) · 'bottom' · 'static' (position it yourself). */
+    position?: 'top' | 'bottom' | 'static';
+    /** Actions pinned to the end of the bar after a divider gap. */
+    end?: ReactNode;
+}
+
+/**
+ * CSS-only tooltip: shows on hover and on keyboard focus, no JS, no
+ * portal. Wraps its child inline.
+ */
+export declare function Tooltip({ label, placement, className, children, ...props }: TooltipProps): JSX_2.Element;
+
+declare interface TooltipProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Bubble content. Keep it to a few words. */
+    label: ReactNode;
+    placement?: 'top' | 'bottom';
+    children: ReactNode;
+}
+
 declare interface TypographyProps extends HTMLAttributes<HTMLElement> {
     as?: ElementType;
 }