@xmesh/system-design 0.0.4 → 0.0.6

package/dist/react/XmFileInput.d.ts

@@ -0,0 +1,151 @@
+import React from "react";
+import {
+  XmFileInput as XmFileInputElement,
+  CustomEvent,
+} from "../lit/components/file-input/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;
+};
+/** `XmFileInput` component event */
+export type XmFileInputElementEvent<E = Event> = TypedEvent<
+  XmFileInputElement,
+  E
+>;
+
+export type { XmFileInputElement, CustomEvent };
+
+export interface XmFileInputProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** Allow selecting more than one file. */
+  multiple?: boolean;
+
+  /** undefined */
+  required?: boolean;
+
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  readOnly?: boolean;
+
+  /** undefined */
+  loading?: boolean;
+
+  /** INITIAL checked for toggle subclasses; mapped from attribute `checked`. */
+  initialChecked?: boolean;
+
+  /** Native accept filter (e.g. ".yml,.json,image/*"). */
+  accept?: XmFileInputElement["accept"];
+
+  /** undefined */
+  label?: XmFileInputElement["label"];
+
+  /** undefined */
+  helper?: XmFileInputElement["helper"];
+
+  /** Severity copy. Non-empty ⇒ the field is in error (icon + copy, never color). */
+  error?: XmFileInputElement["error"];
+
+  /** undefined */
+  size?: XmFileInputElement["size"];
+
+  /** Form-control name — mirrors native <input name>. */
+  name?: XmFileInputElement["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?: XmFileInputElement["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<XmFileInputElement>;
+
+  /** 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;
+
+  /** Public read contract (AD-6a) — the selected files. */
+  files?: XmFileInputElement["files"];
+
+  /** Fired on commit with the new value in `detail`. */
+  onChange?: (event: XmFileInputElementEvent) => void;
+
+  /** Fired on each edit with the current value in `detail` (inherited by every field). */
+  onInput?: (event: XmFileInputElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `accept`: Native accept filter (e.g. ".yml,.json,image/*").
+ * - `multiple`: Allow selecting more than one file.
+ * - `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`.
+ * - `files`: Public read contract (AD-6a) — the selected files. (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 commit with the new value in `detail`.
+ * - `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 XmFileInput: React.ForwardRefExoticComponent<XmFileInputProps>;

package/dist/react/XmFileInput.js

@@ -0,0 +1,70 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/file-input/index.js";
+import {
+  useEventListener,
+  useProperties,
+  createForwardedRefHandler,
+} from "./react-utils.js";
+
+export const XmFileInput = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    multiple,
+    required,
+    disabled,
+    readOnly,
+    loading,
+    initialChecked,
+    accept,
+    label,
+    helper,
+    error,
+    size,
+    name,
+    initialValue,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    files,
+    onChange,
+    onInput,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "change", props.onChange);
+  useEventListener(ref, "input", props.onInput);
+
+  /** Properties - run whenever a property has changed */
+  useProperties(ref, "files", files);
+
+  return React.createElement(
+    "xm-file-input",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      accept: accept,
+      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"],
+      multiple: multiple ? 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,
+  );
+});

package/dist/react/XmFileValidationBlock.d.ts

@@ -0,0 +1,111 @@
+import React from "react";
+import {
+  XmFileValidationBlock as XmFileValidationBlockElement,
+  CustomEvent,
+} from "../lit/components/validation/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;
+};
+/** `XmFileValidationBlock` component event */
+export type XmFileValidationBlockElementEvent<E = Event> = TypedEvent<
+  XmFileValidationBlockElement,
+  E
+>;
+
+export type { XmFileValidationBlockElement, CustomEvent };
+
+export interface XmFileValidationBlockProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  state?: XmFileValidationBlockElement["state"];
+
+  /** undefined */
+  hint?: XmFileValidationBlockElement["hint"];
+
+  /** undefined */
+  fileCsv?: XmFileValidationBlockElement["fileCsv"];
+
+  /** undefined */
+  errorJson?: XmFileValidationBlockElement["errorJson"];
+
+  /** 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<XmFileValidationBlockElement>;
+
+  /** 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;
+
+  /** undefined */
+  onName?: (event: XmFileValidationBlockElementEvent) => void;
+
+  /** Fired when the user requests to pick a file. */
+  onFilePick?: (event: XmFileValidationBlockElementEvent) => void;
+
+  /** Fired when a file is dropped (`detail.file`). */
+  onFileDrop?: (event: XmFileValidationBlockElementEvent) => void;
+
+  /** Fired when the file path is copied (`detail.path`). */
+  onCopyPath?: (event: XmFileValidationBlockElementEvent) => void;
+
+  /** Fired when the validation error is dismissed. */
+  onErrorDismiss?: (event: XmFileValidationBlockElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `state`: undefined
+ * - `hint`: undefined
+ * - `file-csv`/`fileCsv`: undefined
+ * - `error-json`/`errorJson`: undefined
+ * - `file`: undefined (property only)
+ * - `error`: undefined (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `name`: undefined
+ * - `file-pick`: Fired when the user requests to pick a file.
+ * - `file-drop`: Fired when a file is dropped (`detail.file`).
+ * - `copy-path`: Fired when the file path is copied (`detail.path`).
+ * - `error-dismiss`: Fired when the validation error is dismissed.
+ */
+export const XmFileValidationBlock: React.ForwardRefExoticComponent<XmFileValidationBlockProps>;

package/dist/react/XmFileValidationBlock.js

@@ -0,0 +1,50 @@
+import React, { forwardRef, useRef } from "react";
+import "../lit/components/validation/index.js";
+import { useEventListener, createForwardedRefHandler } from "./react-utils.js";
+
+export const XmFileValidationBlock = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
+  const {
+    state,
+    hint,
+    fileCsv,
+    errorJson,
+    className,
+    exportparts,
+    htmlFor,
+    part,
+    tabIndex,
+    onName,
+    onFilePick,
+    onFileDrop,
+    onCopyPath,
+    onErrorDismiss,
+    ...restProps
+  } = props;
+
+  /** Event listeners - run once */
+  useEventListener(ref, "name", props.onName);
+  useEventListener(ref, "file-pick", props.onFilePick);
+  useEventListener(ref, "file-drop", props.onFileDrop);
+  useEventListener(ref, "copy-path", props.onCopyPath);
+  useEventListener(ref, "error-dismiss", props.onErrorDismiss);
+
+  return React.createElement(
+    "xm-file-validation-block",
+    {
+      ref: createForwardedRefHandler(ref, forwardedRef),
+      ...restProps,
+      state: state,
+      hint: hint,
+      "file-csv": fileCsv ?? props["file-csv"],
+      "error-json": errorJson ?? props["error-json"],
+      class: className,
+      exportparts: exportparts,
+      for: htmlFor ?? props["for"],
+      part: part,
+      tabindex: tabIndex ?? props["tabindex"],
+      style: { ...props.style },
+    },
+    props.children,
+  );
+});

package/dist/react/XmForm.d.ts

@@ -0,0 +1,91 @@
+import React from "react";
+import {
+  XmForm as XmFormElement,
+  CustomEvent,
+} from "../lit/components/form/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;
+};
+/** `XmForm` component event */
+export type XmFormElementEvent<E = Event> = TypedEvent<XmFormElement, E>;
+
+export type { XmFormElement, CustomEvent };
+
+export interface XmFormProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  disabled?: boolean;
+
+  /** undefined */
+  readOnly?: 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<XmFormElement>;
+
+  /** 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 form is submitted with its values in `detail`. */
+  onSubmit?: (event: XmFormElementEvent) => void;
+}
+
+/**
+ *
+ *
+ * ## Attributes & Properties
+ *
+ * Component attributes and properties that can be applied to the element or by using JavaScript.
+ *
+ * - `disabled`: undefined
+ * - `readonly`/`readOnly`: undefined
+ * - `readonly`: undefined (property only)
+ *
+ * ## Events
+ *
+ * Events that will be emitted by the component.
+ *
+ * - `submit`: Fired when the form is submitted with its values in `detail`.
+ *
+ * ## Methods
+ *
+ * Methods that can be called to access component functionality.
+ *
+ * - `validate() => FormResult`: Public read contract: pull each child's live value at read time (children
+ * are uncontrolled — the form does not drive their renders, AD-6).
+ * - `submit() => FormResult`: Imperative submit — same path the submit button / Enter take.
+ */
+export const XmForm: React.ForwardRefExoticComponent<XmFormProps>;

package/dist/react/XmForm.js

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

package/dist/react/XmGrid.d.ts

@@ -0,0 +1,59 @@
+import React from "react";
+import { XmGrid as XmGridElement } from "../lit/components/grid/index.js";
+
+export type { XmGridElement };
+
+export interface XmGridProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** undefined */
+  columns?: XmGridElement["columns"];
+
+  /** undefined */
+  gap?: XmGridElement["gap"];
+
+  /** 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<XmGridElement>;
+
+  /** 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.
+ *
+ * - `columns`: undefined
+ * - `gap`: undefined
+ */
+export const XmGrid: React.ForwardRefExoticComponent<XmGridProps>;

package/dist/react/XmGrid.js

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

package/dist/react/XmKbd.d.ts

@@ -0,0 +1,46 @@
+import React from "react";
+import { XmKbd as XmKbdElement } from "../lit/components/kbd/index.js";
+
+export type { XmKbdElement };
+
+export interface XmKbdProps extends Pick<
+  React.AllHTMLAttributes<HTMLElement>,
+  | "children"
+  | "dir"
+  | "hidden"
+  | "id"
+  | "lang"
+  | "slot"
+  | "style"
+  | "title"
+  | "translate"
+  | "onClick"
+  | "onFocus"
+  | "onBlur"
+> {
+  /** 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<XmKbdElement>;
+
+  /** 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;
+}
+
+/**
+ *
+ */
+export const XmKbd: React.ForwardRefExoticComponent<XmKbdProps>;

package/dist/react/XmKbd.js

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