@xmesh/system-design 0.0.4 → 0.0.6

package/dist/react/XmList.d.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import {
+  XmList as XmListElement,
+  CustomEvent,
+} from "../lit/components/list/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;
+};
+/** `XmList` component event */
+export type XmListElementEvent<E = Event> = TypedEvent<XmListElement, E>;
+
+export type { XmListElement, CustomEvent };
+
+export interface XmListProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  interactive?: boolean;
+
+  /** undefined */
+  selectable?: boolean;
+
+  /** 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<XmListElement>;
+
+  /** 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 commit with the new value in `detail`. */
+  onChange?: (event: XmListElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `interactive`: undefined
+ * - `selectable`: undefined
+ * - `value`: undefined (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `change`: Fired on commit with the new value in `detail`.
+ */
+export const XmList: React.ForwardRefExoticComponent<XmListProps>;

package/dist/react/XmList.js

@@ -0,0 +1,38 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/list/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmList = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    interactive,
+    selectable,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    onChange,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "change", props.onChange);
+
+  return React.createElement(
+    "xm-list",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      interactive: interactive ? true : undefined,
+      selectable: selectable ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmListItem.d.ts

@@ -0,0 +1,67 @@
+import React from "react";
+import { XmListItem as XmListItemElement } from "../lit/components/list-item/index.js";
+
+export type { XmListItemElement };
+
+export interface XmListItemProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  selected?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  value?: XmListItemElement["value"];
+
+  /** undefined */
+  secondary?: XmListItemElement["secondary"];
+
+  /** 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<XmListItemElement>;
+
+  /** 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.
+ *
+ * - `value`: undefined
+ * - `selected`: undefined
+ * - `disabled`: undefined
+ * - `secondary`: undefined
+ */
+export const XmListItem: React.ForwardRefExoticComponent<XmListItemProps>;

package/dist/react/XmListItem.js

@@ -0,0 +1,38 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/list-item/index.js";
+import { createForwardedRefHandler } from "./react-utils.js";
+
+export const XmListItem = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    selected,
+    disabled,
+    value,
+    secondary,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  return React.createElement(
+    "xm-list-item",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      value: value,
+      secondary: secondary,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      selected: selected ? true : undefined,
+      disabled: disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmMenu.d.ts

@@ -0,0 +1,98 @@
+import React from "react";
+import {
+  XmMenu as XmMenuElement,
+  CustomEvent,
+} from "../lit/components/menu/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;
+};
+/** `XmMenu` component event */
+export type XmMenuElementEvent<E = Event> = TypedEvent<XmMenuElement, E>;
+
+export type { XmMenuElement, CustomEvent };
+
+export interface XmMenuProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  open?: boolean;
+
+  /** undefined */
+  placement?: XmMenuElement["placement"];
+
+  /** undefined */
+  label?: XmMenuElement["label"];
+
+  /** 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<XmMenuElement>;
+
+  /** 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 element requests to close. */
+  onClose?: (event: XmMenuElementEvent) => void;
+
+  /** Fired when a menu option is selected. */
+  onXmMenuSelect?: (event: XmMenuElementEvent) => void;
+
+  /** Fired when a menu item is activated. */
+  onXmMenuItemActivate?: (event: XmMenuElementEvent) => void;
+
+  /** Fired when a menu item is hovered. */
+  onXmMenuItemHover?: (event: XmMenuElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `open`: undefined
+ * - `placement`: undefined
+ * - `label`: undefined
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `close`: Fired when the element requests to close.
+ * - `xm-menu-select`: Fired when a menu option is selected.
+ * - `xm-menu-item-activate`: Fired when a menu item is activated.
+ * - `xm-menu-item-hover`: Fired when a menu item is hovered.
+ */
+export const XmMenu: React.ForwardRefExoticComponent<XmMenuProps>;

package/dist/react/XmMenu.js

@@ -0,0 +1,46 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/menu/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmMenu = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    open,
+    placement,
+    label,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    onClose,
+    onXmMenuSelect,
+    onXmMenuItemActivate,
+    onXmMenuItemHover,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "close", props.onClose);
+  useEventListener(ref, "xm-menu-select", props.onXmMenuSelect);
+  useEventListener(ref, "xm-menu-item-activate", props.onXmMenuItemActivate);
+  useEventListener(ref, "xm-menu-item-hover", props.onXmMenuItemHover);
+
+  return React.createElement(
+    "xm-menu",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      placement: placement,
+      label: label,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      open: open ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmMenuItem.d.ts

@@ -0,0 +1,63 @@
+import React from "react";
+import { XmMenuItem as XmMenuItemElement } from "../lit/components/menu/index.js";
+
+export type { XmMenuItemElement };
+
+export interface XmMenuItemProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  active?: boolean;
+
+  /** undefined */
+  value?: XmMenuItemElement["value"];
+
+  /** 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<XmMenuItemElement>;
+
+  /** 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.
+ *
+ * - `value`: undefined
+ * - `disabled`: undefined
+ * - `active`: undefined
+ */
+export const XmMenuItem: React.ForwardRefExoticComponent<XmMenuItemProps>;

package/dist/react/XmMenuItem.js

@@ -0,0 +1,36 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/menu/index.js";
+import { createForwardedRefHandler } from "./react-utils.js";
+
+export const XmMenuItem = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    disabled,
+    active,
+    value,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  return React.createElement(
+    "xm-menu-item",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      value: value,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      disabled: disabled ? true : undefined,
+      active: active ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmMultiSelect.d.ts

@@ -0,0 +1,161 @@
+import React from "react";
+import {
+  XmMultiSelect as XmMultiSelectElement,
+  CustomEvent,
+} from "../lit/components/multi-select/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;
+};
+/** `XmMultiSelect` component event */
+export type XmMultiSelectElementEvent<E = Event> = TypedEvent<
+  XmMultiSelectElement,
+  E
+>;
+
+export type { XmMultiSelectElement, CustomEvent };
+
+export interface XmMultiSelectProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Render the in-panel search filter. */
+  searchable?: boolean;
+
+  /** undefined */
+  required?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  readOnly?: boolean;
+
+  /** undefined */
+  loading?: boolean;
+
+  /** INITIAL checked for toggle subclasses; mapped from attribute `checked`. */
+  initialChecked?: boolean;
+
+  /** Shown on the trigger when nothing is selected. */
+  placeholder?: XmMultiSelectElement["placeholder"];
+
+  /** Selection cap (0 = uncapped). At the cap, unselected options disable; selected stay removable. */
+  max?: XmMultiSelectElement["max"];
+
+  /** undefined */
+  label?: XmMultiSelectElement["label"];
+
+  /** undefined */
+  helper?: XmMultiSelectElement["helper"];
+
+  /** Severity copy. Non-empty ⇒ the field is in error (icon + copy, never color). */
+  error?: XmMultiSelectElement["error"];
+
+  /** undefined */
+  size?: XmMultiSelectElement["size"];
+
+  /** Form-control name — mirrors native <input name>. */
+  name?: XmMultiSelectElement["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?: XmMultiSelectElement["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<XmMultiSelectElement>;
+
+  /** 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;
+
+  /** The option model — `{ label, value, disabled? }` shared with xm-select / radio-group. */
+  options?: XmMultiSelectElement["options"];
+
+  /** The selected primitives, in option order. The typed multi-value accessor
+(the inherited string `value` stays a comma-joined mirror for plain consumers). */
+  selectedValues?: XmMultiSelectElement["selectedValues"];
+
+  /** Fired on every toggle; `detail.value` is the full selection as an Array<primitive>. */
+  onChange?: (event: XmMultiSelectElementEvent) => void;
+
+  /** Fired on each edit with the current value in `detail` (inherited by every field). */
+  onInput?: (event: XmMultiSelectElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `placeholder`: Shown on the trigger when nothing is selected.
+ * - `max`: Selection cap (0 = uncapped). At the cap, unselected options disable; selected stay removable.
+ * - `searchable`: Render the in-panel search filter.
+ * - `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`.
+ * - `options`: The option model — `{ label, value, disabled? }` shared with xm-select / radio-group. (property only)
+ * - `selectedValues`: The selected primitives, in option order. The typed multi-value accessor
+ * (the inherited string `value` stays a comma-joined mirror for plain consumers). (property only) (readonly)
+ * - `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.
+ *
+ * - `change`: Fired on every toggle; `detail.value` is the full selection as an Array<primitive>.
+ * - `input`: Fired on each edit with the current 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 XmMultiSelect: React.ForwardRefExoticComponent<XmMultiSelectProps>;