@milktop/react-ui 0.0.0-stage → 0.1.2

package/dist/tree-view/TreeView.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A tree of nested items that open and close, e.g. folders, categories or a
+ * clinic's sites and rooms.
+ *
+ *   <TreeView items={folders} onSelect={(node) => open(node)} />
+ *   <TreeView items={permissions} checkable checked={granted} onCheckedChange={setGranted} />
+ *
+ * Arrow keys move through it (←→ close and open), typing jumps, Enter selects.
+ *
+ * - `items`: `{ value, label, icon, children, disabled }`; a node with
+ *   `children` is a branch (an empty array still opens and closes)
+ * - `selected`, `defaultSelected`; `onSelectedChange`: the selected values;
+ *   `selectionMode`: 'single' (default) or 'multiple'. `onSelect(node)`: an
+ *   item (not a branch) was chosen
+ * - `expanded`, `defaultExpanded`; `onExpandedChange`: the open branches' values
+ * - `checkable`: a checkbox on each (ticking a branch ticks its children);
+ *   `checked`, `defaultChecked`; `onCheckedChange`: the ticked values
+ * - `renderItem(node, { branch, expanded, selected, depth })`: a row's content
+ * - `label`: the tree's name (shown above it, and for assistive tech)
+ *
+ * By hand, Ark's parts are here too: TreeView.Root, Tree, Branch,
+ * BranchControl, BranchText, BranchIndicator, BranchContent, Item, ItemText,
+ * NodeProvider, NodeCheckbox… with `createTreeCollection`.
+ */
+import { type ReactNode } from 'react';
+import { TreeView as Ark, createTreeCollection } from '@ark-ui/react/tree-view';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './tree-view.css';
+export type TreeItem = {
+    value: string;
+    label: ReactNode;
+    icon?: string;
+    children?: TreeItem[];
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+type Render = ((node: TreeItem, state: {
+    branch: boolean;
+    expanded: boolean;
+    selected: boolean;
+    depth: number;
+}) => ReactNode) | undefined;
+export type TreeViewProps = Omit<Ark.RootProps<TreeItem>, 'collection' | 'onSelect' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectionChange' | 'expandedValue' | 'defaultExpandedValue' | 'onExpandedChange' | 'checkedValue' | 'defaultCheckedValue' | 'onCheckedChange'> & {
+    items: TreeItem[];
+    selected?: string[];
+    defaultSelected?: string[];
+    onSelectedChange?: (values: string[]) => void;
+    onSelect?: (node: TreeItem) => void;
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (values: string[]) => void;
+    checkable?: boolean;
+    checked?: string[];
+    defaultChecked?: string[];
+    onCheckedChange?: (values: string[]) => void;
+    renderItem?: Render;
+    label?: ReactNode;
+    classes?: Classes<'root' | 'label' | 'tree' | 'branch' | 'branchControl' | 'branchIndicator' | 'branchText' | 'branchContent' | 'indentGuide' | 'item' | 'itemText' | 'icon' | 'checkbox'>;
+};
+declare function TreeViewShortcut({ items, selected, defaultSelected, onSelectedChange, onSelect, expanded, defaultExpanded, onExpandedChange, checkable, checked, defaultChecked, onCheckedChange, renderItem, label, className, classes, ...rest }: TreeViewProps): import("react").JSX.Element;
+export declare const TreeView: typeof TreeViewShortcut & {
+    Root: Ark.RootComponent<{}>;
+    RootProvider: Ark.RootProviderComponent<{}>;
+    Label: import("react").ForwardRefExoticComponent<Ark.LabelProps & import("react").RefAttributes<HTMLHeadingElement>>;
+    Tree: import("react").ForwardRefExoticComponent<Ark.TreeProps & import("react").RefAttributes<HTMLDivElement>>;
+    Branch: import("react").ForwardRefExoticComponent<Ark.BranchProps & import("react").RefAttributes<HTMLDivElement>>;
+    BranchControl: import("react").ForwardRefExoticComponent<Ark.BranchControlProps & import("react").RefAttributes<HTMLDivElement>>;
+    BranchText: import("react").ForwardRefExoticComponent<Ark.BranchTextProps & import("react").RefAttributes<HTMLSpanElement>>;
+    BranchIndicator: import("react").ForwardRefExoticComponent<Ark.BranchIndicatorProps & import("react").RefAttributes<HTMLDivElement>>;
+    BranchContent: import("react").ForwardRefExoticComponent<Ark.BranchContentProps & import("react").RefAttributes<HTMLDivElement>>;
+    BranchIndentGuide: import("react").ForwardRefExoticComponent<Ark.BranchIndentGuideProps & import("react").RefAttributes<HTMLDivElement>>;
+    BranchTrigger: import("react").ForwardRefExoticComponent<Ark.BranchTriggerProps & import("react").RefAttributes<HTMLDivElement>>;
+    Item: import("react").ForwardRefExoticComponent<Ark.ItemProps & import("react").RefAttributes<HTMLDivElement>>;
+    ItemText: import("react").ForwardRefExoticComponent<Ark.ItemTextProps & import("react").RefAttributes<HTMLSpanElement>>;
+    ItemIndicator: import("react").ForwardRefExoticComponent<Ark.ItemIndicatorProps & import("react").RefAttributes<HTMLDivElement>>;
+    NodeProvider: typeof Ark.NodeProvider;
+    NodeCheckbox: import("react").ForwardRefExoticComponent<Ark.NodeCheckboxProps & import("react").RefAttributes<HTMLSpanElement>>;
+    NodeCheckboxIndicator: {
+        (props: Ark.NodeCheckboxIndicatorProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    Context: <T extends unknown>(props: Ark.ContextProps<T>) => ReactNode;
+};
+export { createTreeCollection };

package/dist/tree-view/TreeView.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * A tree of nested items that open and close, e.g. folders, categories or a
+ * clinic's sites and rooms.
+ *
+ *   <TreeView items={folders} onSelect={(node) => open(node)} />
+ *   <TreeView items={permissions} checkable checked={granted} onCheckedChange={setGranted} />
+ *
+ * Arrow keys move through it (←→ close and open), typing jumps, Enter selects.
+ *
+ * - `items`: `{ value, label, icon, children, disabled }`; a node with
+ *   `children` is a branch (an empty array still opens and closes)
+ * - `selected`, `defaultSelected`; `onSelectedChange`: the selected values;
+ *   `selectionMode`: 'single' (default) or 'multiple'. `onSelect(node)`: an
+ *   item (not a branch) was chosen
+ * - `expanded`, `defaultExpanded`; `onExpandedChange`: the open branches' values
+ * - `checkable`: a checkbox on each (ticking a branch ticks its children);
+ *   `checked`, `defaultChecked`; `onCheckedChange`: the ticked values
+ * - `renderItem(node, { branch, expanded, selected, depth })`: a row's content
+ * - `label`: the tree's name (shown above it, and for assistive tech)
+ *
+ * By hand, Ark's parts are here too: TreeView.Root, Tree, Branch,
+ * BranchControl, BranchText, BranchIndicator, BranchContent, Item, ItemText,
+ * NodeProvider, NodeCheckbox… with `createTreeCollection`.
+ */
+import { useMemo } from 'react';
+import { TreeView as Ark, createTreeCollection, useTreeViewNodeContext } from '@ark-ui/react/tree-view';
+import 'iconify-icon';
+import { cx, on, partsOf, withParts } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './tree-view.css';
+function TreeViewShortcut({ items, selected, defaultSelected, onSelectedChange, onSelect, expanded, defaultExpanded, onExpandedChange, checkable = false, checked, defaultChecked, onCheckedChange, renderItem, label = null, className, classes, ...rest }) {
+    const t = useMessages();
+    const part = partsOf('tree-view', classes);
+    const collection = useMemo(() => createTreeCollection({
+        nodeToValue: (node) => node.value,
+        nodeToString: (node) => (typeof node.label === 'string' ? node.label : node.value),
+        isNodeDisabled: (node) => !!node.disabled,
+        rootNode: { value: 'ROOT', label: '', children: items },
+    }), [items]);
+    return (_jsxs(Ark.Root, { ...(t.zag.treeView && { translations: t.zag.treeView }), ...rest, ...part('root'), className: cx(className, classes?.root), collection: collection, ...(selected !== undefined && { selectedValue: selected }), ...(defaultSelected && { defaultSelectedValue: defaultSelected }), ...(expanded !== undefined && { expandedValue: expanded }), ...(defaultExpanded && { defaultExpandedValue: defaultExpanded }), ...(checked !== undefined && { checkedValue: checked }), ...(defaultChecked && { defaultCheckedValue: defaultChecked }), ...((onSelectedChange || onSelect) && {
+            onSelectionChange: (details) => {
+                onSelectedChange?.(details.selectedValue);
+                // A single item chosen (not a branch): onSelect gets it.
+                // (The focused one, or the last chosen: Zag may not have moved focus yet.)
+                const nodes = details.selectedNodes;
+                const node = nodes.find((n) => n.value === details.focusedValue) ?? nodes[nodes.length - 1];
+                if (node && !node.children)
+                    onSelect?.(node);
+            },
+        }), ...on('onExpandedChange', onExpandedChange, (d) => d.expandedValue), ...on('onCheckedChange', onCheckedChange, (d) => d.checkedValue), children: [label && _jsx(Ark.Label, { ...part('label'), children: label }), _jsx(Ark.Tree, { ...part('tree'), children: items.map((node, i) => _jsx(Node, { node: node, indexPath: [i], part: part, checkable: checkable, renderItem: renderItem }, node.value)) })] }));
+}
+function Node({ node, indexPath, part, checkable, renderItem }) {
+    return (_jsx(Ark.NodeProvider, { node: node, indexPath: indexPath, children: node.children
+            ? _jsxs(Ark.Branch, { ...part('branch'), children: [_jsxs(Ark.BranchControl, { ...part('branch-control'), children: [_jsx(Ark.BranchIndicator, { ...part('branch-indicator'), children: _jsx("iconify-icon", { icon: "lucide:chevron-right" }) }), _jsx(Row, { node: node, part: part, checkable: checkable, renderItem: renderItem })] }), _jsxs(Ark.BranchContent, { ...part('branch-content'), children: [_jsx(Ark.BranchIndentGuide, { ...part('indent-guide') }), node.children.map((child, i) => (_jsx(Node, { node: child, indexPath: [...indexPath, i], part: part, checkable: checkable, renderItem: renderItem }, child.value)))] })] })
+            : _jsx(Ark.Item, { ...part('item'), children: _jsx(Row, { node: node, part: part, checkable: checkable, renderItem: renderItem }) }) }));
+}
+// A row's checkbox, icon and text (or your render).
+function Row({ node, part, checkable, renderItem }) {
+    const state = useTreeViewNodeContext();
+    const branch = !!node.children;
+    const Text = branch ? Ark.BranchText : Ark.ItemText;
+    return _jsxs(_Fragment, { children: [checkable && (_jsx(Ark.NodeCheckbox, { ...part('checkbox'), onClick: (e) => e.stopPropagation(), children: _jsx(Ark.NodeCheckboxIndicator, { indeterminate: _jsx("iconify-icon", { icon: "lucide:minus" }), children: _jsx("iconify-icon", { icon: "lucide:check" }) }) })), renderItem
+                ? _jsx(Text, { ...part(branch ? 'branch-text' : 'item-text'), children: renderItem(node, { branch, expanded: state.expanded, selected: state.selected, depth: state.depth }) })
+                : _jsxs(_Fragment, { children: [(node.icon ?? branch) && (_jsx("iconify-icon", { ...part('icon'), "aria-hidden": "true", icon: node.icon ?? (state.expanded ? 'lucide:folder-open' : 'lucide:folder') })), _jsx(Text, { ...part(branch ? 'branch-text' : 'item-text'), children: node.label })] })] });
+}
+export const TreeView = withParts(TreeViewShortcut, {
+    Root: Ark.Root, RootProvider: Ark.RootProvider, Label: Ark.Label, Tree: Ark.Tree, Branch: Ark.Branch, BranchControl: Ark.BranchControl,
+    BranchText: Ark.BranchText, BranchIndicator: Ark.BranchIndicator, BranchContent: Ark.BranchContent, BranchIndentGuide: Ark.BranchIndentGuide,
+    BranchTrigger: Ark.BranchTrigger, Item: Ark.Item, ItemText: Ark.ItemText, ItemIndicator: Ark.ItemIndicator, NodeProvider: Ark.NodeProvider,
+    NodeCheckbox: Ark.NodeCheckbox, NodeCheckboxIndicator: Ark.NodeCheckboxIndicator, Context: Ark.Context,
+});
+export { createTreeCollection };

package/dist/tree-view/tree-view.css

@@ -0,0 +1,29 @@
+@layer ui {
+  [data-scope=tree-view][data-part=root] { display: block; min-width: 0; color: var(--ui-text); font-family: var(--ui-font); font-size: 14px; }
+  [data-scope=tree-view][data-part=label] { display: block; margin-bottom: 0.375rem; font-size: 14px; font-weight: 500; }
+  [data-scope=tree-view][data-part=tree] { display: flex; flex-direction: column; gap: 1px; outline: none; }
+  /* A row: indented by its depth (Zag sets --depth), a chevron for branches, then checkbox, icon and text. */
+  [data-scope=tree-view]:is([data-part=branch-control], [data-part=item]) {
+    display: flex; align-items: center; gap: 0.375rem; min-height: 2rem; box-sizing: border-box;
+    padding: 0 0.5rem 0 calc(0.5rem + (var(--depth, 1) - 1) * 1.25rem); border-radius: var(--ui-radius);
+    cursor: pointer; user-select: none; outline: none;
+    &:hover { background: var(--ui-hover); }
+    &[data-selected] { background: var(--ui-accent-soft); color: var(--ui-accent-soft-text); }
+    &[data-focus]:focus-visible { box-shadow: inset 0 0 0 2px var(--ui-ring-soft); }
+    &[data-disabled] { opacity: 0.5; cursor: not-allowed; } }
+  /* Items line up with branch texts (past the chevron's room). */
+  [data-scope=tree-view][data-part=item] { padding-left: calc(0.5rem + (var(--depth, 1) - 1) * 1.25rem + 1.375rem); }
+  [data-scope=tree-view][data-part=branch-indicator] { display: grid; place-items: center; width: 1rem; color: var(--ui-muted); font-size: 14px;
+    transition: rotate 150ms;
+    &[data-state=open] { rotate: 90deg; } }
+  [data-scope=tree-view][data-part=icon] { flex-shrink: 0; color: var(--ui-muted); font-size: 16px;
+    [data-selected] > & { color: inherit; } }
+  [data-scope=tree-view]:is([data-part=branch-text], [data-part=item-text]) { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  [data-scope=tree-view][data-part=branch-content] { position: relative; display: flex; flex-direction: column; gap: 1px; }
+  /* A faint line down the open branch's children. */
+  [data-scope=tree-view][data-part=indent-guide] { position: absolute; top: 0; bottom: 0; width: 1px; background: var(--ui-border);
+    left: calc(0.5rem + (var(--depth, 1) - 1) * 1.25rem + 0.5rem); }
+  [data-scope=tree-view][data-part=checkbox] { display: grid; place-items: center; flex-shrink: 0; width: 1rem; height: 1rem; box-sizing: border-box;
+    border: 1px solid var(--ui-border); border-radius: 4px; background: var(--ui-surface); color: var(--ui-accent-text); font-size: 11px;
+    &:is([data-state=checked], [data-state=indeterminate]) { background: var(--ui-accent); border-color: var(--ui-accent); } }
+}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentProps, ElementType, ReactNode } from 'react';
+type ClassName = string | false | null | undefined | ClassName[];
+export declare const cx: (...names: ClassName[]) => string | undefined;
+export type Classes<Part extends string> = Partial<Record<Part, string>>;
+export declare const partsOf: (scope: string, classes?: Partial<Record<string, string>>) => (name: string) => {
+    'data-scope': string;
+    'data-part': string;
+    className: string | undefined;
+};
+export declare function partOf<T extends ElementType = 'div'>(scope: string, name: string, tag?: T): {
+    (props: ComponentProps<T>): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+    displayName: string;
+};
+export declare const withParts: <S extends object, P extends object>(Shortcut: S, parts: P) => S & P;
+export type Slot<State> = ReactNode | ((state: State) => ReactNode);
+export declare function slot<State>(value: Slot<State> | undefined, fallback: ReactNode, state: State): ReactNode;
+export declare function useControllable<V>(value: V | undefined, defaultValue: V, onChange?: (value: V) => void): readonly [V, (next: V) => void];
+export declare function on<Name extends string, Details, Value>(name: Name, handler: ((value: Value, details: Details) => void) | undefined, pick: (details: Details) => Value): Partial<Record<Name, (details: Details) => void>>;
+export {};

package/dist/utils.js

@@ -0,0 +1,59 @@
+import { createElement, useCallback, useState } from 'react';
+// Joins the truthy class names (nested arrays too).
+export const cx = (...names) => names.map((name) => (Array.isArray(name) ? cx(...name) : name)).filter(Boolean).join(' ') || undefined;
+// A component's parts carry Zag-style data-scope and data-part attributes,
+// which the library's CSS targets, so a part never matches another
+// component's rules, and the library adds no classes of its own to collide
+// with yours or Tailwind's. Each part also gets the caller's classes for it,
+// from the `classes` prop, keyed by camelCased part name:
+//
+//   const part = partsOf('select', classes)
+//   <Ark.Trigger {...part('trigger')}>   // classes={{ trigger: '…' }}
+//
+// Ark merges our props over its own, so on an Ark part these win: that's
+// how Sheet's parts say data-scope="sheet" on Ark's dialog. Where the scopes
+// match they're the same values Ark sets anyway.
+const camel = (name) => name.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+export const partsOf = (scope, classes) => (name) => ({
+    'data-scope': scope,
+    'data-part': name,
+    className: cx(classes?.[camel(name)]),
+});
+// A part of our own (not Ark's), for building a component by hand; it takes
+// the props of its element (a div by default):
+//   Dialog.Footer = partOf('dialog', 'footer')   // <Dialog.Footer>…</Dialog.Footer>
+export function partOf(scope, name, tag = 'div') {
+    const Part = (props) => createElement(tag, { 'data-scope': scope, 'data-part': name, ...props });
+    Part.displayName = `${scope}.${name}`;
+    return Part;
+}
+// The shortcut component, with its parts on it for building it by hand:
+//   export const Checkbox = withParts(CheckboxShortcut, { Root: Ark.Root, … })
+//   <Checkbox label="…" />  or  <Checkbox.Root>…</Checkbox.Root>
+export const withParts = (Shortcut, parts) => Object.assign(Shortcut, parts);
+// A slot's content: the default when it's absent.
+//   {slot(indicator, <CheckIcon />, { indeterminate })}
+export function slot(value, fallback, state) {
+    if (value == null)
+        return fallback;
+    return typeof value === 'function' ? value(state) : value;
+}
+// A value that's controlled when `value` is given, and kept here otherwise
+// (starting from `defaultValue`). Calls onChange either way.
+export function useControllable(value, defaultValue, onChange) {
+    const [own, setOwn] = useState(defaultValue);
+    const controlled = value !== undefined;
+    const set = useCallback((next) => {
+        if (!controlled)
+            setOwn(next);
+        onChange?.(next);
+    }, [controlled, onChange]);
+    return [controlled ? value : own, set];
+}
+// A change handler given the value rather than Ark's details object, and
+// left out when there's none: Zag reads a prop passed as undefined as a
+// value, overriding its default.
+//   <Ark.Root {...rest} {...on('onCheckedChange', onCheckedChange, (d) => d.checked)}>
+export function on(name, handler, pick) {
+    return handler ? { [name]: (details) => handler(pick(details), details) } : {};
+}

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@milktop/react-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "React components on Ark UI (Zag state machines), with imba-ui's API and design",
+  "license": "MIT",
+  "author": "André Goldstein",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/milktop/react-ui.git"
+  },
+  "homepage": "https://github.com/milktop/react-ui#readme",
+  "bugs": {
+    "url": "https://github.com/milktop/react-ui/issues"
+  },
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "ark-ui",
+    "zag",
+    "design-system"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "vite playground --port 5194",
+    "build": "vite build playground",
+    "build:lib": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/after-tsc.js",
+    "check": "tsc && eslint src playground",
+    "prepublishOnly": "npm run build:lib",
+    "preversion": "npm run check && npm run build:lib",
+    "postversion": "git push --follow-tags",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish",
+    "release:beta": "npm version prerelease --preid beta && npm publish --tag beta"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@ark-ui/react": "^5.39.3",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@internationalized/date": "^3.12.4",
+    "@tiptap/core": "^3.31.4",
+    "@tiptap/extension-image": "^3.31.4",
+    "@tiptap/extensions": "^3.31.4",
+    "@tiptap/pm": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-shape": "^3.2.0",
+    "@zag-js/date-utils": "^1.45.0",
+    "@zag-js/file-utils": "^1.45.0",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0",
+    "iconify-icon": "^3.0.3"
+  },
+  "devDependencies": {
+    "@fontsource-variable/dm-sans": "^5.3.0",
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/plus-jakarta-sans": "^5.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vite": "^8.3.4"
+  }
+}