@zag-js/toolbar 2.0.0-next.1

package/dist/toolbar.types.d.mts

@@ -0,0 +1,148 @@
+import { Machine, EventObject, Service } from '@zag-js/core';
+import { PropTypes, Orientation, RequiredBy, DirectionProperty, CommonProperties } from '@zag-js/types';
+export { Orientation } from '@zag-js/types';
+
+type ElementIds = Partial<{
+    root: string;
+    item: (value: string) => string;
+    group: (value: string) => string;
+}>;
+interface ToolbarProps extends DirectionProperty, CommonProperties {
+    /**
+     * The ids of the elements in the toolbar. Useful for composition.
+     */
+    ids?: ElementIds | undefined;
+    /**
+     * Whether the toolbar is disabled. This cascades into every item's
+     * effective `disabled` state, but never affects `getLinkProps`.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * The orientation of the toolbar.
+     * @default "horizontal"
+     */
+    orientation?: Orientation | undefined;
+    /**
+     * Whether to loop focus inside the toolbar when navigating with the keyboard.
+     * @default true
+     */
+    loopFocus?: boolean | undefined;
+}
+type PropsWithDefault = "orientation" | "loopFocus";
+interface PrivateContext {
+    /**
+     * The value of the item that currently holds the roving tabindex.
+     * Persists across blur, so tabbing away and back resumes at the same item.
+     */
+    focusedValue: string | null;
+    /**
+     * Whether the root has ever redirected focus to an item. Once true, the root
+     * permanently cedes its own tabindex to whichever item is tracked.
+     */
+    hasInteracted: boolean;
+    /**
+     * Whether the toolbar was focused by a click.
+     */
+    isClickFocus: boolean;
+}
+interface ToolbarSchema {
+    props: RequiredBy<ToolbarProps, PropsWithDefault>;
+    context: PrivateContext;
+    state: "idle" | "focused";
+    event: EventObject;
+    action: string;
+    guard: string;
+    effect: string;
+}
+type ToolbarService = Service<ToolbarSchema>;
+type ToolbarMachine = Machine<ToolbarSchema>;
+interface ItemProps {
+    /**
+     * The unique value of the item.
+     */
+    value: string;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Whether the item remains focusable (and reachable via arrow keys) while disabled.
+     * Keeping disabled controls in the roving tabindex sequence makes them discoverable.
+     * @default true
+     */
+    focusableWhenDisabled?: boolean | undefined;
+}
+interface ItemState {
+    /**
+     * The underlying id of the item.
+     */
+    id: string;
+    /**
+     * Whether the item is disabled. When `focusableWhenDisabled` is `true`, guard your
+     * own action handler with this, e.g. `onClick={itemState.disabled ? undefined : fn}`.
+     */
+    disabled: boolean;
+    /**
+     * Whether the item remains focusable (and reachable via arrow keys) while disabled.
+     */
+    focusableWhenDisabled: boolean;
+    /**
+     * Whether the item is the current roving tabindex target.
+     */
+    focused: boolean;
+    /**
+     * The orientation of the toolbar this item belongs to.
+     */
+    orientation: Orientation;
+}
+interface LinkProps {
+    /**
+     * The unique value of the link.
+     */
+    value: string;
+}
+interface GroupProps {
+    /**
+     * The unique value of the group.
+     */
+    value: string;
+    /**
+     * Whether the group is disabled. This is a purely visual/ARIA concern —
+     * it does not automatically cascade into the disabled state of items
+     * rendered inside it. Thread it into each item's own `disabled` prop, e.g.
+     * `api.getItemProps({ value, disabled: groupDisabled || itemDisabled })`.
+     */
+    disabled?: boolean | undefined;
+}
+interface ToolbarApi<T extends PropTypes = PropTypes> {
+    /**
+     * Whether the toolbar is disabled.
+     */
+    disabled: boolean;
+    /**
+     * The value of the item that is currently focused, if any.
+     */
+    focusedValue: string | null;
+    /**
+     * The orientation of the toolbar.
+     */
+    orientation: Orientation;
+    /**
+     * Returns the resolved DOM id for the given item value. Useful for aligning
+     * a composed machine's own id (e.g. `select`'s `ids.trigger`) with a toolbar
+     * item, so the two machines agree on one DOM node.
+     */
+    getItemId: (value: string) => string;
+    /**
+     * Returns the state details of the given item.
+     */
+    getItemState: (props: ItemProps) => ItemState;
+    getRootProps: () => T["element"];
+    getGroupProps: (props: GroupProps) => T["element"];
+    getSeparatorProps: () => T["element"];
+    getItemProps: (props: ItemProps) => T["button"];
+    getLinkProps: (props: LinkProps) => T["element"];
+    getInputProps: (props: ItemProps) => T["input"];
+}
+
+export type { ElementIds, GroupProps, ItemProps, ItemState, LinkProps, ToolbarApi, ToolbarMachine, ToolbarProps, ToolbarSchema, ToolbarService };

package/dist/toolbar.types.d.ts

@@ -0,0 +1,148 @@
+import { Machine, EventObject, Service } from '@zag-js/core';
+import { PropTypes, Orientation, RequiredBy, DirectionProperty, CommonProperties } from '@zag-js/types';
+export { Orientation } from '@zag-js/types';
+
+type ElementIds = Partial<{
+    root: string;
+    item: (value: string) => string;
+    group: (value: string) => string;
+}>;
+interface ToolbarProps extends DirectionProperty, CommonProperties {
+    /**
+     * The ids of the elements in the toolbar. Useful for composition.
+     */
+    ids?: ElementIds | undefined;
+    /**
+     * Whether the toolbar is disabled. This cascades into every item's
+     * effective `disabled` state, but never affects `getLinkProps`.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * The orientation of the toolbar.
+     * @default "horizontal"
+     */
+    orientation?: Orientation | undefined;
+    /**
+     * Whether to loop focus inside the toolbar when navigating with the keyboard.
+     * @default true
+     */
+    loopFocus?: boolean | undefined;
+}
+type PropsWithDefault = "orientation" | "loopFocus";
+interface PrivateContext {
+    /**
+     * The value of the item that currently holds the roving tabindex.
+     * Persists across blur, so tabbing away and back resumes at the same item.
+     */
+    focusedValue: string | null;
+    /**
+     * Whether the root has ever redirected focus to an item. Once true, the root
+     * permanently cedes its own tabindex to whichever item is tracked.
+     */
+    hasInteracted: boolean;
+    /**
+     * Whether the toolbar was focused by a click.
+     */
+    isClickFocus: boolean;
+}
+interface ToolbarSchema {
+    props: RequiredBy<ToolbarProps, PropsWithDefault>;
+    context: PrivateContext;
+    state: "idle" | "focused";
+    event: EventObject;
+    action: string;
+    guard: string;
+    effect: string;
+}
+type ToolbarService = Service<ToolbarSchema>;
+type ToolbarMachine = Machine<ToolbarSchema>;
+interface ItemProps {
+    /**
+     * The unique value of the item.
+     */
+    value: string;
+    /**
+     * Whether the item is disabled.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Whether the item remains focusable (and reachable via arrow keys) while disabled.
+     * Keeping disabled controls in the roving tabindex sequence makes them discoverable.
+     * @default true
+     */
+    focusableWhenDisabled?: boolean | undefined;
+}
+interface ItemState {
+    /**
+     * The underlying id of the item.
+     */
+    id: string;
+    /**
+     * Whether the item is disabled. When `focusableWhenDisabled` is `true`, guard your
+     * own action handler with this, e.g. `onClick={itemState.disabled ? undefined : fn}`.
+     */
+    disabled: boolean;
+    /**
+     * Whether the item remains focusable (and reachable via arrow keys) while disabled.
+     */
+    focusableWhenDisabled: boolean;
+    /**
+     * Whether the item is the current roving tabindex target.
+     */
+    focused: boolean;
+    /**
+     * The orientation of the toolbar this item belongs to.
+     */
+    orientation: Orientation;
+}
+interface LinkProps {
+    /**
+     * The unique value of the link.
+     */
+    value: string;
+}
+interface GroupProps {
+    /**
+     * The unique value of the group.
+     */
+    value: string;
+    /**
+     * Whether the group is disabled. This is a purely visual/ARIA concern —
+     * it does not automatically cascade into the disabled state of items
+     * rendered inside it. Thread it into each item's own `disabled` prop, e.g.
+     * `api.getItemProps({ value, disabled: groupDisabled || itemDisabled })`.
+     */
+    disabled?: boolean | undefined;
+}
+interface ToolbarApi<T extends PropTypes = PropTypes> {
+    /**
+     * Whether the toolbar is disabled.
+     */
+    disabled: boolean;
+    /**
+     * The value of the item that is currently focused, if any.
+     */
+    focusedValue: string | null;
+    /**
+     * The orientation of the toolbar.
+     */
+    orientation: Orientation;
+    /**
+     * Returns the resolved DOM id for the given item value. Useful for aligning
+     * a composed machine's own id (e.g. `select`'s `ids.trigger`) with a toolbar
+     * item, so the two machines agree on one DOM node.
+     */
+    getItemId: (value: string) => string;
+    /**
+     * Returns the state details of the given item.
+     */
+    getItemState: (props: ItemProps) => ItemState;
+    getRootProps: () => T["element"];
+    getGroupProps: (props: GroupProps) => T["element"];
+    getSeparatorProps: () => T["element"];
+    getItemProps: (props: ItemProps) => T["button"];
+    getLinkProps: (props: LinkProps) => T["element"];
+    getInputProps: (props: ItemProps) => T["input"];
+}
+
+export type { ElementIds, GroupProps, ItemProps, ItemState, LinkProps, ToolbarApi, ToolbarMachine, ToolbarProps, ToolbarSchema, ToolbarService };

package/dist/toolbar.types.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/toolbar.types.ts
+var toolbar_types_exports = {};
+module.exports = __toCommonJS(toolbar_types_exports);

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@zag-js/toolbar",
+  "version": "2.0.0-next.1",
+  "description": "Core logic for the toolbar widget implemented as a state machine",
+  "keywords": [
+    "js",
+    "machine",
+    "xstate",
+    "statechart",
+    "component",
+    "chakra-ui",
+    "toolbar"
+  ],
+  "author": "Segun Adebayo <sage@adebayosegun.com>",
+  "homepage": "https://github.com/chakra-ui/zag#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chakra-ui/zag/tree/main/packages/toolbar"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/chakra-ui/zag/issues"
+  },
+  "dependencies": {
+    "@zag-js/anatomy": "2.0.0-next.1",
+    "@zag-js/dom-query": "2.0.0-next.1",
+    "@zag-js/utils": "2.0.0-next.1",
+    "@zag-js/core": "2.0.0-next.1",
+    "@zag-js/types": "2.0.0-next.1"
+  },
+  "devDependencies": {
+    "clean-package": "2.2.0"
+  },
+  "clean-package": "./clean-package.config.json",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./anatomy": {
+      "import": {
+        "types": "./dist/toolbar.anatomy.d.mts",
+        "default": "./dist/toolbar.anatomy.mjs"
+      },
+      "require": {
+        "types": "./dist/toolbar.anatomy.d.ts",
+        "default": "./dist/toolbar.anatomy.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit"
+  }
+}