@stealthscale/component-actions 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -1,99 +1,486 @@
-import { ComponentProps, JSX } from "react";
+import { ComponentProps, JSX, ReactElement, ReactNode } from "react";
+import * as clipboard from "@zag-js/clipboard";
+import { FileMimeType } from "@zag-js/file-utils";
+import * as toggle from "@zag-js/toggle-group";
+import { Group } from "@stealthscale/component-layout";
 //#region src/button/button.d.ts
 /**
- * Draws a button in a look, a size and a status, square where it holds one glyph.
+ * Renders an element with the button recipe's classes.
  */
-export declare const Button: import("@stealthscale/theme").StyledComponent<"button", {
-  readonly effect?: "glow" | "ripple";
-  readonly elevation?: import("@stealthscale/theme/authoring").Lift;
-  readonly shape?: "square";
-  readonly size?: import("@stealthscale/theme/authoring").Scale;
-  readonly status?: "error" | "info" | "success" | "warning";
-  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface";
+declare const Bound$1: import("@stealthscale/theme").StyledComponent<"button", {
+  readonly effect?: "glow" | "pulse" | undefined;
+  readonly elevation?: import("@stealthscale/theme/authoring").Lift | undefined;
+  readonly palette?: "accent" | "error" | "info" | "neutral" | "primary" | "secondary" | "success" | "warning" | undefined;
+  readonly shape?: "square" | undefined;
+  readonly size?: import("@stealthscale/theme/authoring").Scale | undefined;
+  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface" | undefined;
 }>;
 /**
- * Describes what a button takes: the variants its recipe offers, and everything a styled button
- * element takes.
+ * Combines the recipe's variants with the props of a `button` element.
  */
-type ButtonProps = ComponentProps<typeof Button>;
+type ButtonProps = ComponentProps<typeof Bound$1>;
+/**
+ * Renders a `button` element with `type` defaulting to `button`, so a button inside a form does not
+ * submit it.
+ *
+ * @remarks
+ *   An element that `as` names takes a `type` only from the caller, because an `a` reads `type` as
+ *   the media type of the page it opens.
+ * @param props - The recipe's variants and the props of the element.
+ * @returns The element with the button's classes.
+ */
+export declare function Button(props: ButtonProps): ReactElement;
 //#endregion
 //#region src/button/context.d.ts
 /**
- * Binds the button's recipe to the elements that draw it.
+ * Binds the button recipe to the elements that render it.
  *
  * @remarks
- *   Apart from the recipe, because an application's compiler reads the recipe at build time and
- *   the binding needs the runtime. A recipe file that also bound one would put the runtime behind
- *   every compiler configuration that reads it.
+ *   The binding is kept out of `recipe.ts` because an application's style compiler imports the
+ *   recipe at build time, and a binding there would pull the React runtime into that import.
  */
 /**
- * Binds the recipe once, for the button, for the square that holds one glyph, and for whatever
- * sets their variants from above.
+ * Supplies the element factory `Button` and `IconButton` are built from, and the provider an
+ * ancestor sets their variants through.
  */
 declare const PropsProvider: import("react").Provider<import("@stealthscale/theme").DataAttrs & Partial<{
-  readonly effect?: "glow" | "ripple";
-  readonly elevation?: import("@stealthscale/theme/authoring").Lift;
-  readonly shape?: "square";
-  readonly size?: import("@stealthscale/theme/authoring").Scale;
-  readonly status?: "error" | "info" | "success" | "warning";
-  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface";
+  readonly effect?: "glow" | "pulse" | undefined;
+  readonly elevation?: import("@stealthscale/theme/authoring").Lift | undefined;
+  readonly palette?: "accent" | "error" | "info" | "neutral" | "primary" | "secondary" | "success" | "warning" | undefined;
+  readonly shape?: "square" | undefined;
+  readonly size?: import("@stealthscale/theme/authoring").Scale | undefined;
+  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface" | undefined;
 }>>, withContext: <Tag extends import("react").ElementType>(Component: Tag, options?: import("@stealthscale/theme").JsxFactoryOptions<import("@stealthscale/theme").ComponentProps<Tag> & Partial<{
-  readonly effect?: "glow" | "ripple";
-  readonly elevation?: import("@stealthscale/theme/authoring").Lift;
-  readonly shape?: "square";
-  readonly size?: import("@stealthscale/theme/authoring").Scale;
-  readonly status?: "error" | "info" | "success" | "warning";
-  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface";
-}>> | undefined) => import("@stealthscale/theme").StyledComponent<Tag, {
-  readonly effect?: "glow" | "ripple";
-  readonly elevation?: import("@stealthscale/theme/authoring").Lift;
-  readonly shape?: "square";
-  readonly size?: import("@stealthscale/theme/authoring").Scale;
-  readonly status?: "error" | "info" | "success" | "warning";
-  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface";
+  readonly effect?: "glow" | "pulse" | undefined;
+  readonly elevation?: import("@stealthscale/theme/authoring").Lift | undefined;
+  readonly palette?: "accent" | "error" | "info" | "neutral" | "primary" | "secondary" | "success" | "warning" | undefined;
+  readonly shape?: "square" | undefined;
+  readonly size?: import("@stealthscale/theme/authoring").Scale | undefined;
+  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface" | undefined;
+}>, string> | undefined) => import("@stealthscale/theme").StyledComponent<Tag, {
+  readonly effect?: "glow" | "pulse" | undefined;
+  readonly elevation?: import("@stealthscale/theme/authoring").Lift | undefined;
+  readonly palette?: "accent" | "error" | "info" | "neutral" | "primary" | "secondary" | "success" | "warning" | undefined;
+  readonly shape?: "square" | undefined;
+  readonly size?: import("@stealthscale/theme/authoring").Scale | undefined;
+  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface" | undefined;
 }>;
 //#endregion
 //#region src/button/icon-button.d.ts
 /**
- * Binds the button's recipe with the square shape fixed, beside the button's own default type.
+ * Renders an element with the button recipe's classes and `shape` defaulting to `square`.
  */
-declare const Square: import("@stealthscale/theme").StyledComponent<"button", {
-  readonly effect?: "glow" | "ripple";
-  readonly elevation?: import("@stealthscale/theme/authoring").Lift;
-  readonly shape?: "square";
-  readonly size?: import("@stealthscale/theme/authoring").Scale;
-  readonly status?: "error" | "info" | "success" | "warning";
-  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface";
+declare const Bound: import("@stealthscale/theme").StyledComponent<"button", {
+  readonly effect?: "glow" | "pulse" | undefined;
+  readonly elevation?: import("@stealthscale/theme/authoring").Lift | undefined;
+  readonly palette?: "accent" | "error" | "info" | "neutral" | "primary" | "secondary" | "success" | "warning" | undefined;
+  readonly shape?: "square" | undefined;
+  readonly size?: import("@stealthscale/theme/authoring").Scale | undefined;
+  readonly variant?: "ghost" | "glass" | "outline" | "plain" | "solid" | "subtle" | "surface" | undefined;
 }>;
 /**
- * Gives the control a label of its own.
+ * Renders a square `button` element with `type` defaulting to `button`.
+ *
+ * @remarks
+ *   An element that `as` names takes a `type` only from the caller, because an `a` reads `type` as
+ *   the media type of the page it opens.
+ * @param props - The recipe's variants and the props of the element.
+ * @returns The element with the button's classes.
+ */
+declare function Square(props: ComponentProps<typeof Bound>): ReactElement;
+/**
+ * Describes the prop that gives the control its accessible name as text.
  */
 interface Labelled {
   /**
-   * The words that name the control.
+   * The accessible name a screen reader announces in place of the icon.
    */
   "aria-label": string;
 }
 /**
- * Points the control at the element that holds its name.
+ * Describes the prop that takes the control's accessible name from another element.
  */
 interface LabelledBy {
   /**
-   * The id of the element that holds the words.
+   * The id of the element whose text names the control.
    */
   "aria-labelledby": string;
 }
 /**
- * Requires an accessible name for a control whose content gives it none.
+ * Requires `aria-label` or `aria-labelledby`.
  */
 type Named = Labelled | LabelledBy;
 /**
- * Describes what an icon button takes: everything a button takes, and an accessible name.
+ * Combines the square button's props with the accessible-name requirement.
  */
 type IconButtonProps = ComponentProps<typeof Square> & Named;
 /**
- * Draws a square button in a look, a size and a status, named in words for the glyph it holds.
+ * Renders a square button around one icon, named by `aria-label` or `aria-labelledby`.
  */
 export declare const IconButton: (props: IconButtonProps) => JSX.Element;
 //#endregion
-export { type ButtonProps, PropsProvider as ButtonPropsProvider, type IconButtonProps };
+//#region src/clipboard/machine.d.ts
+/**
+ * API returned by `clipboard.connect`: a prop getter per part, the machine state and its methods.
+ *
+ * @remarks
+ *   The type derives from `connect`, so it follows the installed machine version. The derived type
+ *   references `@zag-js/types`, so the package declares that package as a dependency. A
+ *   declaration file that references an undeclared package does not resolve for a consumer.
+ */
+type ClipboardApi = ReturnType<typeof clipboard.connect>;
+/**
+ * Machine settings a caller passes to the root, `id` included, all optional.
+ *
+ * @remarks
+ *   `translations` is omitted. The trigger takes its accessible names as the props `label` and
+ *   `copiedLabel`, because a component's words are props with English defaults.
+ */
+type ClipboardOptions = Omit<Partial<clipboard.Props>, "translations">;
+//#endregion
+//#region src/clipboard/consumer.d.ts
+/**
+ * Props of `Clipboard.Consumer`: the render function.
+ */
+interface ConsumerProps {
+  /**
+   * Render function called with the machine's API.
+   */
+  readonly children: (api: ClipboardApi) => ReactNode;
+}
+/**
+ * Calls the render function with the API of the nearest root.
+ *
+ * @param props - The render function, as `children`.
+ * @returns The tree the render function returns.
+ */
+declare function Consumer({ children }: ConsumerProps): ReactNode;
+//#endregion
+//#region src/clipboard/control.d.ts
+/**
+ * `div` bound to the control slot.
+ */
+declare const Styled$6: import("@stealthscale/theme").StyledComponent<"div", {}>;
+/**
+ * Props of `Clipboard.Control`: the props of the styled `div`.
+ */
+type ControlProps = ComponentProps<typeof Styled$6>;
+/**
+ * Renders the row with the caller's props merged over the machine's.
+ *
+ * @param props - Props of the styled `div`.
+ * @returns The row, with the `data-copied` attribute the machine sets after a copy.
+ */
+declare function Control(props: ControlProps): ReactElement;
+//#endregion
+//#region src/clipboard/indicator.d.ts
+/**
+ * `span` bound to the indicator slot.
+ */
+declare const Styled$5: import("@stealthscale/theme").StyledComponent<"span", {}>;
+/**
+ * Props of `Clipboard.Indicator`: the props of the styled `span` and the copied mark.
+ */
+interface IndicatorProps$1 extends ComponentProps<typeof Styled$5> {
+  /**
+   * Mark rendered during the copied state.
+   */
+  readonly copied?: ReactNode;
+}
+/**
+ * Renders `children` in the idle state and `copied` in the copied state.
+ *
+ * @param props - The two marks and the props of the styled `span`.
+ * @returns The span, hidden from assistive technology unless the caller overrides `aria-hidden`.
+ */
+declare function Indicator$1({ children, copied, ...rest }: IndicatorProps$1): ReactElement;
+//#endregion
+//#region src/clipboard/input.d.ts
+/**
+ * `input` bound to the input slot.
+ */
+declare const Styled$4: import("@stealthscale/theme").StyledComponent<"input", {}>;
+/**
+ * Props of `Clipboard.Input`: the props of the styled `input`.
+ */
+type InputProps = ComponentProps<typeof Styled$4>;
+/**
+ * Renders the field with the caller's props merged over the machine's.
+ *
+ * @param props - Props of the styled `input`.
+ * @returns The read-only field that holds the machine's value.
+ */
+declare function Input(props: InputProps): ReactElement;
+//#endregion
+//#region src/clipboard/label.d.ts
+/**
+ * `label` bound to the label slot.
+ */
+declare const Styled$3: import("@stealthscale/theme").StyledComponent<"label", {}>;
+/**
+ * Props of `Clipboard.Label`: the props of the styled `label`.
+ */
+type LabelProps = ComponentProps<typeof Styled$3>;
+/**
+ * Renders the label with the caller's props merged over the machine's.
+ *
+ * @param props - Props of the styled `label`.
+ * @returns The label, whose `for` attribute points at the field.
+ */
+declare function Label(props: LabelProps): ReactElement;
+//#endregion
+//#region src/clipboard/root.d.ts
+/**
+ * `div` bound to the root slot, which provides the recipe's variants to the parts.
+ */
+declare const Styled$2: import("@stealthscale/theme").StyledComponent<"div", {
+  readonly size?: "lg" | "md" | "sm" | undefined;
+}>;
+/**
+ * Props of `Clipboard.Root`: the machine settings and the props of the styled `div`.
+ *
+ * @remarks
+ *   The element props omit `id` and `dir`, which the machine owns, and `defaultValue`, which is
+ *   the machine's initial value.
+ */
+interface RootProps$2 extends ClipboardOptions, Omit<ComponentProps<typeof Styled$2>, "defaultValue" | "dir" | "id"> {}
+/**
+ * Starts a clipboard machine and renders the container its parts read from.
+ *
+ * @param props - Machine settings, recipe variants and `div` props.
+ * @returns The container, with the connected API in context.
+ */
+declare function Root$2(props: RootProps$2): ReactElement;
+//#endregion
+//#region src/clipboard/trigger.d.ts
+/**
+ * `button` bound to the trigger slot.
+ */
+declare const Styled$1: import("@stealthscale/theme").StyledComponent<"button", {}>;
+/**
+ * Props of `Clipboard.Trigger`: the two accessible names and the props of the styled `button`.
+ */
+interface TriggerProps extends ComponentProps<typeof Styled$1> {
+  /**
+   * Accessible name in the copied state. Defaults to "Copied to clipboard".
+   */
+  readonly copiedLabel?: string | undefined;
+  /**
+   * Accessible name in the idle state. Defaults to "Copy to clipboard".
+   */
+  readonly label?: string | undefined;
+}
+/**
+ * Renders the button with the caller's props merged over the machine's.
+ *
+ * @remarks
+ *   An `aria-label` the caller passes takes precedence over both names.
+ * @param props - The two accessible names and the props of the styled `button`.
+ * @returns The button, wired to the machine's copy handler.
+ */
+declare function Trigger({ copiedLabel, label, ...rest }: TriggerProps): ReactElement;
+//#endregion
+//#region src/clipboard/value-text.d.ts
+/**
+ * `span` bound to the valueText slot.
+ */
+declare const Styled: import("@stealthscale/theme").StyledComponent<"span", {}>;
+/**
+ * Props of `Clipboard.ValueText`: the props of the styled `span`.
+ */
+type ValueTextProps = ComponentProps<typeof Styled>;
+/**
+ * Renders the caller's children, or the machine's value when there are none.
+ *
+ * @param props - Props of the styled `span`.
+ * @returns The span with the children or the value.
+ */
+declare function ValueText({ children, ...rest }: ValueTextProps): ReactElement;
+declare namespace index_d_exports {
+  export { Consumer, ConsumerProps, Control, ControlProps, Indicator$1 as Indicator, IndicatorProps$1 as IndicatorProps, Input, InputProps, Label, LabelProps, Root$2 as Root, RootProps$2 as RootProps, Trigger, TriggerProps, ValueText, ValueTextProps };
+}
+//#endregion
+//#region src/color-mode-toggle/color-mode-toggle.d.ts
+/**
+ * Describes the props of the toggle: its two glyphs, its name and the props of a `Button`.
+ */
+interface ColorModeToggleProps extends Omit<ButtonProps, "aria-label" | "aria-labelledby" | "aria-pressed" | "children"> {
+  /**
+   * Glyph shown while the page is dark.
+   */
+  readonly dark: ReactNode;
+  /**
+   * Name of the button in both states, "Dark mode" unless the caller passes another.
+   */
+  readonly label?: string | undefined;
+  /**
+   * Glyph shown while the page is light.
+   */
+  readonly light: ReactNode;
+}
+/**
+ * Renders the actions `Button` as a ghost, neutral square that sets the other color mode on a press
+ * the caller did not cancel.
+ *
+ * @param props - The two glyphs, the name and the props of a `Button`.
+ * @returns The `button` element.
+ */
+export declare function ColorModeToggle({ dark, label, light, onClick, ...props }: ColorModeToggleProps): ReactElement;
+//#endregion
+//#region src/download-trigger/download.d.ts
+/**
+ * Contents of a file: text, a `Blob` or a `File`.
+ */
+type DownloadableData = Blob | string;
+/**
+ * Options of `download`, which `DownloadTrigger` takes as props.
+ */
+interface DownloadOptions {
+  /**
+   * Contents of the file, or a function called on every download that returns them or a promise of
+   * them.
+   */
+  readonly data: (() => DownloadableData | Promise<DownloadableData>) | DownloadableData;
+  /**
+   * Name the browser saves the file under, extension included.
+   */
+  readonly fileName: string;
+  /**
+   * Type of text data. A `Blob` or a `File` keeps its own type.
+   */
+  readonly mimeType?: FileMimeType | undefined;
+}
+/**
+ * Resolves the data and hands it to the browser as a file.
+ *
+ * @returns A promise that settles once the browser has the file, and rejects when the data
+ *   function throws or its promise rejects.
+ */
+export declare function download({ data, fileName, mimeType }: DownloadOptions): Promise<void>;
+//#endregion
+//#region src/download-trigger/download-trigger.d.ts
+/**
+ * Props of `DownloadTrigger`: the download options and the props of `Button`.
+ */
+interface DownloadTriggerProps extends ButtonProps, DownloadOptions {}
+/**
+ * Renders a button that downloads `data` as `fileName` when pressed.
+ *
+ * @remarks
+ *   `onClick` runs first. A handler that calls `preventDefault` cancels the download.
+ */
+export declare function DownloadTrigger({ data, fileName, mimeType, onClick, ...rest }: DownloadTriggerProps): ReactElement;
+//#endregion
+//#region src/swap/indicator.d.ts
+/**
+ * Renders the `span` with the swap's indicator class.
+ */
+declare const Drawn: import("@stealthscale/theme").StyledComponent<"span", {}>;
+/**
+ * Describes the props of an indicator: which mark it is and the props of a `span`, without `ref`,
+ * which the presence takes.
+ */
+interface IndicatorProps extends Omit<ComponentProps<typeof Drawn>, "ref"> {
+  /**
+   * Which mark this is: `on` shows while the root's `swap` is true, `off` while it is false.
+   */
+  readonly type: "off" | "on";
+}
+/**
+ * Renders the mark with its presence's `data-state` and `inert`, and `data-hidden` in place of
+ * `hidden`, under the caller's props.
+ *
+ * @param props - Which mark this is and the props of a `span`.
+ * @returns The `span` element, or nothing while the presence renders nothing.
+ */
+declare function Indicator({ type, ...props }: IndicatorProps): null | ReactElement;
+//#endregion
+//#region src/swap/root.d.ts
+/**
+ * Renders the `span` with the swap's root class.
+ */
+declare const Framed: import("@stealthscale/theme").StyledComponent<"span", {
+  readonly motion?: "fade" | "none" | "scale" | "slide" | undefined;
+}>;
+/**
+ * Describes the props of the root: which mark shows, how the marks render while hidden, the
+ * recipe's `motion` and the props of a `span`.
+ */
+interface RootProps$1 extends ComponentProps<typeof Framed> {
+  /**
+   * Whether a mark renders nothing until it first shows. False unless the caller passes true.
+   */
+  readonly lazyMount?: boolean | undefined;
+  /**
+   * Whether the `on` mark shows. False unless the caller passes true, which shows the `off` mark.
+   */
+  readonly swap?: boolean | undefined;
+  /**
+   * Whether a mark renders nothing once its exit motion ends. False unless the caller passes true.
+   */
+  readonly unmountOnExit?: boolean | undefined;
+}
+/**
+ * Renders the root and provides which mark shows to the indicators.
+ *
+ * @param props - Which mark shows, how the marks render while hidden, the motion and the props of a
+ *   `span`.
+ * @returns The `span` element inside the state's provider.
+ */
+declare function Root$1({ lazyMount, swap, unmountOnExit, ...props }: RootProps$1): ReactElement;
+declare namespace index_d_exports$1 {
+  export { Indicator, IndicatorProps, Root$1 as Root, RootProps$1 as RootProps };
+}
+//#endregion
+//#region src/toggle-group/machine.d.ts
+/**
+ * Describes the machine options the root takes, every one optional.
+ */
+type ToggleGroupOptions = Partial<toggle.Props>;
+/**
+ * Describes the options of one item: its value, and whether it is disabled.
+ */
+type ItemOptions = toggle.ItemProps;
+/**
+ * Describes what `onValueChange` receives: the values of the items that are on.
+ */
+type ValueChangeDetails = toggle.ValueChangeDetails;
+//#endregion
+//#region src/toggle-group/item.d.ts
+/**
+ * Describes the props of an item: its value, whether it is disabled, and the props of the button.
+ *
+ * @remarks
+ *   The button's own `value` is left out, so `value` names the item.
+ */
+interface ItemProps extends ItemOptions, Omit<ButtonProps, keyof ItemOptions> {}
+/**
+ * Renders the item as a button with the machine's item props.
+ *
+ * @param props - The item's options and the props of the button.
+ * @returns The `button` element.
+ */
+declare function Item(props: ItemProps): ReactElement;
+//#endregion
+//#region src/toggle-group/root.d.ts
+/**
+ * Describes the props of the root: the machine's options, the props of the layout's `Group`, and
+ * the size, look and palette of the items.
+ *
+ * @remarks
+ *   The group's own props of the same names as the machine's options are left out, so no prop has
+ *   two types.
+ */
+interface RootProps extends Omit<ComponentProps<typeof Group>, keyof ToggleGroupOptions>, Pick<ButtonProps, "palette" | "size" | "variant">, ToggleGroupOptions {}
+/**
+ * Renders the group and provides the machine's api and the items' variants.
+ *
+ * @param props - The machine's options, the group's props and the items' variants.
+ * @returns The `div` element that contains the items.
+ */
+declare function Root(props: RootProps): ReactElement;
+declare namespace index_d_exports$2 {
+  export { Item, ItemProps, Root, RootProps, ValueChangeDetails };
+}
+//#endregion
+export { type ButtonProps, PropsProvider as ButtonPropsProvider, index_d_exports as Clipboard, type ColorModeToggleProps, type DownloadOptions, type DownloadTriggerProps, type DownloadableData, type IconButtonProps, index_d_exports$1 as Swap, index_d_exports$2 as ToggleGroup };