@xmesh/system-design 0.0.4 → 0.0.5

package/dist/react/XmBubbleGroup.js

@@ -0,0 +1,36 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/bubble/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmBubbleGroup = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    variant,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "artifact-download", props.onArtifactDownload);
+  useEventListener(ref, "artifact-open", props.onArtifactOpen);
+
+  return React.createElement(
+    "xm-bubble-group",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      variant: variant,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmButton.d.ts

@@ -0,0 +1,89 @@
+import React from "react";
+import { XmButton as XmButtonElement } from "../lit/components/button/index.js";
+
+export type { XmButtonElement };
+
+export interface XmButtonProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  iconOnly?: boolean;
+
+  /** undefined */
+  fullWidth?: boolean;
+
+  /** Persistent active/selected state — used by toggle/tab buttons. Reuses
+the same .is-active visual the design canvases trigger via forceState. */
+  selected?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  loading?: boolean;
+
+  /** undefined */
+  variant?: XmButtonElement["variant"];
+
+  /** undefined */
+  size?: XmButtonElement["size"];
+
+  /** undefined */
+  type?: XmButtonElement["type"];
+
+  /** undefined */
+  forceState?: XmButtonElement["forceState"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: React.Ref<XmButtonElement>;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `variant`: undefined
+ * - `size`: undefined
+ * - `icon-only`/`iconOnly`: undefined
+ * - `full-width`/`fullWidth`: undefined
+ * - `selected`: Persistent active/selected state — used by toggle/tab buttons. Reuses
+ * the same .is-active visual the design canvases trigger via forceState.
+ * - `type`: undefined
+ * - `disabled`: undefined
+ * - `loading`: undefined
+ * - `force-state`/`forceState`: undefined
+ */
+export const XmButton: React.ForwardRefExoticComponent<XmButtonProps>;

package/dist/react/XmButton.js

@@ -0,0 +1,48 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/button/index.js";
+import { createForwardedRefHandler } from "./react-utils.js";
+
+export const XmButton = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    iconOnly,
+    fullWidth,
+    selected,
+    disabled,
+    loading,
+    variant,
+    size,
+    type,
+    forceState,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  return React.createElement(
+    "xm-button",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      variant: variant,
+      size: size,
+      type: type,
+      "force-state": forceState ?? props["force-state"],
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      "icon-only": iconOnly ? true : undefined,
+      "full-width": fullWidth ? true : undefined,
+      selected: selected ? true : undefined,
+      disabled: disabled ? true : undefined,
+      loading: loading ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmCard.d.ts

@@ -0,0 +1,59 @@
+import React from "react";
+import { XmCard as XmCardElement } from "../lit/components/card/index.js";
+
+export type { XmCardElement };
+
+export interface XmCardProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  elevation?: XmCardElement["elevation"];
+
+  /** undefined */
+  size?: XmCardElement["size"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: React.Ref<XmCardElement>;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `elevation`: undefined
+ * - `size`: undefined
+ */
+export const XmCard: React.ForwardRefExoticComponent<XmCardProps>;

package/dist/react/XmCard.js

@@ -0,0 +1,34 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/card/index.js";
+import { createForwardedRefHandler } from "./react-utils.js";
+
+export const XmCard = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    elevation,
+    size,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  return React.createElement(
+    "xm-card",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      elevation: elevation,
+      size: size,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmChatShell.d.ts

@@ -0,0 +1,110 @@
+import React from "react";
+import { XmChatShell as XmChatShellElement } from "../lit/components/chat/index.js";
+
+/**
+ * A generic type for strongly typing custom events with their targets
+ * @template T - The type of the event target (extends EventTarget)
+ * @template D - The type of the detail payload for the custom event
+ */
+type TypedEvent<T extends EventTarget, E = Event> = E & {
+  target: T;
+};
+/** `XmChatShell` component event */
+export type XmChatShellElementEvent<E = Event> = TypedEvent<
+  XmChatShellElement,
+  E
+>;
+
+export type { XmChatShellElement };
+
+export interface XmChatShellProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  processing?: boolean;
+
+  /** Pin the shell to the viewport (height: 100vh). Default is height: 100%
+so the shell sizes to its container — embedded hosts get correct
+sizing for free. Full-bleed previews opt in via the `full-viewport`
+attribute. */
+  fullViewport?: boolean;
+
+  /** undefined */
+  thinkingLabel?: XmChatShellElement["thinkingLabel"];
+
+  /** undefined */
+  topTitle?: XmChatShellElement["topTitle"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: React.Ref<XmChatShellElement>;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** Fired when the artifact panel is closed. */
+  onArtifactClose?: (event: XmChatShellElementEvent) => void;
+
+  /** Fired when an artifact is opened. */
+  onArtifactOpen?: (event: XmChatShellElementEvent) => void;
+
+  /** Fired when the action is cancelled. */
+  onCancel?: (event: XmChatShellElementEvent) => void;
+
+  /** Fired when the user sends the composed content. */
+  onSend?: (event: XmChatShellElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `processing`: undefined
+ * - `thinking-label`/`thinkingLabel`: undefined
+ * - `top-title`/`topTitle`: undefined
+ * - `full-viewport`/`fullViewport`: Pin the shell to the viewport (height: 100vh). Default is height: 100%
+ * so the shell sizes to its container — embedded hosts get correct
+ * sizing for free. Full-bleed previews opt in via the `full-viewport`
+ * attribute.
+ * - `conversations`: undefined (property only)
+ * - `thread`: undefined (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `artifact-close`: Fired when the artifact panel is closed.
+ * - `artifact-open`: Fired when an artifact is opened.
+ * - `cancel`: Fired when the action is cancelled.
+ * - `send`: Fired when the user sends the composed content.
+ */
+export const XmChatShell: React.ForwardRefExoticComponent<XmChatShellProps>;

package/dist/react/XmChatShell.js

@@ -0,0 +1,44 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/chat/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmChatShell = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    processing,
+    fullViewport,
+    thinkingLabel,
+    topTitle,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "artifact-close", props.onArtifactClose);
+  useEventListener(ref, "artifact-open", props.onArtifactOpen);
+  useEventListener(ref, "cancel", props.onCancel);
+  useEventListener(ref, "send", props.onSend);
+
+  return React.createElement(
+    "xm-chat-shell",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      "thinking-label": thinkingLabel ?? props["thinking-label"],
+      "top-title": topTitle ?? props["top-title"],
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      processing: processing ? true : undefined,
+      "full-viewport": fullViewport ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmCheckbox.d.ts

@@ -0,0 +1,145 @@
+import React from "react";
+import {
+  XmCheckbox as XmCheckboxElement,
+  CustomEvent,
+} from "../lit/components/checkbox/index.js";
+
+/**
+ * A generic type for strongly typing custom events with their targets
+ * @template T - The type of the event target (extends EventTarget)
+ * @template D - The type of the detail payload for the custom event
+ */
+type TypedEvent<T extends EventTarget, E = Event> = E & {
+  target: T;
+};
+/** `XmCheckbox` component event */
+export type XmCheckboxElementEvent<E = Event> = TypedEvent<
+  XmCheckboxElement,
+  E
+>;
+
+export type { XmCheckboxElement, CustomEvent };
+
+export interface XmCheckboxProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Indeterminate (mixed) state — shows the dash mark on the coral fill and
+reports aria-checked="mixed". Cleared on the first user toggle. */
+  indeterminate?: boolean;
+
+  /** undefined */
+  required?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  readOnly?: boolean;
+
+  /** undefined */
+  loading?: boolean;
+
+  /** INITIAL checked for toggle subclasses; mapped from attribute `checked`. */
+  initialChecked?: boolean;
+
+  /** undefined */
+  label?: XmCheckboxElement["label"];
+
+  /** undefined */
+  helper?: XmCheckboxElement["helper"];
+
+  /** Severity copy. Non-empty ⇒ the field is in error (icon + copy, never color). */
+  error?: XmCheckboxElement["error"];
+
+  /** undefined */
+  size?: XmCheckboxElement["size"];
+
+  /** Form-control name — mirrors native <input name>. */
+  name?: XmCheckboxElement["name"];
+
+  /** INITIAL value (uncontrolled-first, AD-6): the `value` attribute seeds the
+live state once, then never overrides user input. Mapped from attribute
+`value` so authors write `<xm-text-field value="…">`. */
+  initialValue?: XmCheckboxElement["initialValue"];
+
+  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
+  className?: string;
+
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+
+  /** Used for labels to link them with their inputs (using input id). */
+  htmlFor?: string;
+
+  /** Used to help React identify which items have changed, are added, or are removed within a list. */
+  key?: number | string;
+
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+
+  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
+  ref?: React.Ref<XmCheckboxElement>;
+
+  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
+  tabIndex?: number;
+
+  /** Fired on each edit with the current value in `detail` (inherited by every field). */
+  onInput?: (event: XmCheckboxElementEvent) => void;
+
+  /** Fired on commit with the new value in `detail` (inherited by every field). */
+  onChange?: (event: XmCheckboxElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `indeterminate`: Indeterminate (mixed) state — shows the dash mark on the coral fill and
+ * reports aria-checked="mixed". Cleared on the first user toggle.
+ * - `label`: undefined
+ * - `helper`: undefined
+ * - `error`: Severity copy. Non-empty ⇒ the field is in error (icon + copy, never color).
+ * - `size`: undefined
+ * - `required`: undefined
+ * - `disabled`: undefined
+ * - `readonly`/`readOnly`: undefined
+ * - `loading`: undefined
+ * - `name`: Form-control name — mirrors native <input name>.
+ * - `value`/`initialValue`: INITIAL value (uncontrolled-first, AD-6): the `value` attribute seeds the
+ * live state once, then never overrides user input. Mapped from attribute
+ * `value` so authors write `<xm-text-field value="…">`.
+ * - `checked`/`initialChecked`: INITIAL checked for toggle subclasses; mapped from attribute `checked`.
+ * - `readonly`: undefined (property only)
+ * - `value`: Programmatic reset support — setting `value` after first paint updates live state. (property only)
+ * - `checked`: Public read contract for toggle subclasses (AD-6a). (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `input`: Fired on each edit with the current value in `detail` (inherited by every field).
+ * - `change`: Fired on commit with the new value in `detail` (inherited by every field).
+ *
+ * ## Methods
+ *
+ * Methods that can be called to access component functionality.
+ *
+ * - `setFormDisabled(disabled: boolean) => void`: Down-propagation hook: xm-form (Story 2.10) sets this; it OR's with the
+ * field's own disabled and can never re-enable a self-disabled field.
+ */
+export const XmCheckbox: React.ForwardRefExoticComponent<XmCheckboxProps>;

package/dist/react/XmCheckbox.js

@@ -0,0 +1,58 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/checkbox/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmCheckbox = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    indeterminate,
+    required,
+    disabled,
+    readOnly,
+    loading,
+    initialChecked,
+    label,
+    helper,
+    error,
+    size,
+    name,
+    initialValue,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "input", props.onInput);
+  useEventListener(ref, "change", props.onChange);
+
+  return React.createElement(
+    "xm-checkbox",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      label: label,
+      helper: helper,
+      error: error,
+      size: size,
+      name: name,
+      value: initialValue ?? props["value"],
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      indeterminate: indeterminate ? true : undefined,
+      required: required ? true : undefined,
+      disabled: disabled ? true : undefined,
+      readonly: readOnly ? true : undefined,
+      loading: loading ? true : undefined,
+      checked: initialChecked ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});