@xmesh/system-design 0.0.4 → 0.0.5

package/dist/react/XmChip.d.ts

@@ -0,0 +1,99 @@
+import React from "react";
+import { XmChip as XmChipElement } from "../lit/components/chip/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;
+};
+/** `XmChip` component event */
+export type XmChipElementEvent<E = Event> = TypedEvent<XmChipElement, E>;
+
+export type { XmChipElement };
+
+export interface XmChipProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  selected?: boolean;
+
+  /** undefined */
+  removable?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  value?: XmChipElement["value"];
+
+  /** undefined */
+  size?: XmChipElement["size"];
+
+  /** undefined */
+  category?: XmChipElement["category"];
+
+  /** 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<XmChipElement>;
+
+  /** 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 chip is activated. */
+  onXmChipActivate?: (event: XmChipElementEvent) => void;
+
+  /** Fired when the chip's remove affordance is activated. */
+  onXmChipRemove?: (event: XmChipElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `value`: undefined
+ * - `size`: undefined
+ * - `selected`: undefined
+ * - `removable`: undefined
+ * - `disabled`: undefined
+ * - `category`: undefined
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `xm-chip-activate`: Fired when the chip is activated.
+ * - `xm-chip-remove`: Fired when the chip's remove affordance is activated.
+ */
+export const XmChip: React.ForwardRefExoticComponent<XmChipProps>;

package/dist/react/XmChip.js

@@ -0,0 +1,46 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/chip/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmChip = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    selected,
+    removable,
+    disabled,
+    value,
+    size,
+    category,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "xm-chip-activate", props.onXmChipActivate);
+  useEventListener(ref, "xm-chip-remove", props.onXmChipRemove);
+
+  return React.createElement(
+    "xm-chip",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      value: value,
+      size: size,
+      category: category,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      selected: selected ? true : undefined,
+      removable: removable ? true : undefined,
+      disabled: disabled ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmChipGroup.d.ts

@@ -0,0 +1,79 @@
+import React from "react";
+import { XmChipGroup as XmChipGroupElement } from "../lit/components/chip-group/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;
+};
+/** `XmChipGroup` component event */
+export type XmChipGroupElementEvent<E = Event> = TypedEvent<
+  XmChipGroupElement,
+  E
+>;
+
+export type { XmChipGroupElement };
+
+export interface XmChipGroupProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  multiple?: 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<XmChipGroupElement>;
+
+  /** 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: XmChipGroupElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `multiple`: 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 XmChipGroup: React.ForwardRefExoticComponent<XmChipGroupProps>;

package/dist/react/XmChipGroup.js

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

package/dist/react/XmCode.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import { XmCode as XmCodeElement } from "../lit/components/code/index.js";
+
+export type { XmCodeElement };
+
+export interface XmCodeProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  block?: 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<XmCodeElement>;
+
+  /** 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.
+ *
+ * - `block`: undefined
+ */
+export const XmCode: React.ForwardRefExoticComponent<XmCodeProps>;

package/dist/react/XmCode.js

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

package/dist/react/XmComposer.d.ts

@@ -0,0 +1,123 @@
+import React from "react";
+import {
+  XmComposer as XmComposerElement,
+  CustomEvent,
+} from "../lit/components/composer/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;
+};
+/** `XmComposer` component event */
+export type XmComposerElementEvent<E = Event> = TypedEvent<
+  XmComposerElement,
+  E
+>;
+
+export type { XmComposerElement, CustomEvent };
+
+export interface XmComposerProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  initialFocus?: boolean;
+
+  /** undefined */
+  processing?: boolean;
+
+  /** undefined */
+  showAttachments?: boolean;
+
+  /** undefined */
+  initialValue?: XmComposerElement["initialValue"];
+
+  /** undefined */
+  thinkingLabel?: XmComposerElement["thinkingLabel"];
+
+  /** undefined */
+  maxChars?: XmComposerElement["maxChars"];
+
+  /** undefined */
+  counterAt?: XmComposerElement["counterAt"];
+
+  /** undefined */
+  placeholder?: XmComposerElement["placeholder"];
+
+  /** 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<XmComposerElement>;
+
+  /** 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 value changes (`detail.value`). */
+  onValueChange?: (event: XmComposerElementEvent) => void;
+
+  /** Fired when the attachment set changes. */
+  onAttachmentsChange?: (event: XmComposerElementEvent) => void;
+
+  /** Fired when the action is cancelled. */
+  onCancel?: (event: XmComposerElementEvent) => void;
+
+  /** Fired when the user sends the composed content. */
+  onSend?: (event: XmComposerElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `initial-value`/`initialValue`: undefined
+ * - `initial-focus`/`initialFocus`: undefined
+ * - `processing`: undefined
+ * - `thinking-label`/`thinkingLabel`: undefined
+ * - `max-chars`/`maxChars`: undefined
+ * - `counter-at`/`counterAt`: undefined
+ * - `placeholder`: undefined
+ * - `show-attachments`/`showAttachments`: undefined
+ * - `value`: undefined (property only)
+ * - `attachments`: undefined (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `value-change`: Fired when the value changes (`detail.value`).
+ * - `attachments-change`: Fired when the attachment set changes.
+ * - `cancel`: Fired when the action is cancelled.
+ * - `send`: Fired when the user sends the composed content.
+ */
+export const XmComposer: React.ForwardRefExoticComponent<XmComposerProps>;

package/dist/react/XmComposer.js

@@ -0,0 +1,52 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/composer/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmComposer = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    initialFocus,
+    processing,
+    showAttachments,
+    initialValue,
+    thinkingLabel,
+    maxChars,
+    counterAt,
+    placeholder,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "value-change", props.onValueChange);
+  useEventListener(ref, "attachments-change", props.onAttachmentsChange);
+  useEventListener(ref, "cancel", props.onCancel);
+  useEventListener(ref, "send", props.onSend);
+
+  return React.createElement(
+    "xm-composer",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      "initial-value": initialValue ?? props["initial-value"],
+      "thinking-label": thinkingLabel ?? props["thinking-label"],
+      "max-chars": maxChars ?? props["max-chars"],
+      "counter-at": counterAt ?? props["counter-at"],
+      placeholder: placeholder,
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      "initial-focus": initialFocus ? true : undefined,
+      processing: processing ? true : undefined,
+      "show-attachments": showAttachments ? true : undefined,
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmDataTable.d.ts

@@ -0,0 +1,125 @@
+import React from "react";
+import {
+  XmDataTable as XmDataTableElement,
+  CustomEvent,
+} from "../lit/components/data-table/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;
+};
+/** `XmDataTable` component event */
+export type XmDataTableElementEvent<E = Event> = TypedEvent<
+  XmDataTableElement,
+  E
+>;
+
+export type { XmDataTableElement, CustomEvent };
+
+export interface XmDataTableProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  loading?: boolean;
+
+  /** Server/controlled mode (AD-14): the consumer owns sort + paging. The table
+renders `rows` verbatim, never sorts/slices a copy, derives the page count
+from `total-items` (not `rows.length`), and emits intents only. */
+  server?: boolean;
+
+  /** Make rows clickable — emits xm-data-table-row-click (AD-15). */
+  rowClick?: boolean;
+
+  /** undefined */
+  pageSize?: XmDataTableElement["pageSize"];
+
+  /** undefined */
+  emptyHeading?: XmDataTableElement["emptyHeading"];
+
+  /** undefined */
+  emptyText?: XmDataTableElement["emptyText"];
+
+  /** Total item count for server-mode paging (pages = ceil(total-items/page-size)). */
+  totalItems?: XmDataTableElement["totalItems"];
+
+  /** 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<XmDataTableElement>;
+
+  /** 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;
+
+  /** Controlled sort indicator for server mode (`{ key, direction }`); reflected,
+never reordered locally. */
+  sort?: XmDataTableElement["sort"];
+
+  /** Fired when the page changes (`detail.page`). */
+  onXmDataTablePageChange?: (event: XmDataTableElementEvent) => void;
+
+  /** Fired when the sort changes (`detail.key`, `detail.direction`). */
+  onXmDataTableSortChange?: (event: XmDataTableElementEvent) => void;
+
+  /** Fired when a clickable row is activated (`detail.row`, `detail.index`). */
+  onXmDataTableRowClick?: (event: XmDataTableElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `loading`: undefined
+ * - `page-size`/`pageSize`: undefined
+ * - `empty-heading`/`emptyHeading`: undefined
+ * - `empty-text`/`emptyText`: undefined
+ * - `server`: Server/controlled mode (AD-14): the consumer owns sort + paging. The table
+ * renders `rows` verbatim, never sorts/slices a copy, derives the page count
+ * from `total-items` (not `rows.length`), and emits intents only.
+ * - `total-items`/`totalItems`: Total item count for server-mode paging (pages = ceil(total-items/page-size)).
+ * - `row-click`/`rowClick`: Make rows clickable — emits xm-data-table-row-click (AD-15).
+ * - `columns`: undefined (property only)
+ * - `rows`: undefined (property only)
+ * - `sort`: Controlled sort indicator for server mode (`{ key, direction }`); reflected,
+ * never reordered locally. (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `xm-data-table-page-change`: Fired when the page changes (`detail.page`).
+ * - `xm-data-table-sort-change`: Fired when the sort changes (`detail.key`, `detail.direction`).
+ * - `xm-data-table-row-click`: Fired when a clickable row is activated (`detail.row`, `detail.index`).
+ */
+export const XmDataTable: React.ForwardRefExoticComponent<XmDataTableProps>;