@lo-tek/interfaces 0.0.0-stage → 0.37.0

package/src/index.ts

@@ -0,0 +1,218 @@
+export type {
+  AccordionAttributes,
+  AccordionOptions,
+  AccordionVariant,
+} from "./components/css/accordion/accordion.js"
+export { accordion } from "./components/css/accordion/accordion.js"
+export type {
+  AlertAttributes,
+  AlertColor,
+  AlertOptions,
+} from "./components/css/alert/alert.js"
+export { alert } from "./components/css/alert/alert.js"
+export type {
+  AvatarAttributes,
+  AvatarOptions,
+  AvatarSize,
+  AvatarVariant,
+} from "./components/css/avatar/avatar.js"
+export { avatar } from "./components/css/avatar/avatar.js"
+export type {
+  BadgeAttributes,
+  BadgeColor,
+  BadgeOptions,
+} from "./components/css/badge/badge.js"
+export { badge } from "./components/css/badge/badge.js"
+export type { BreadcrumbsAttributes } from "./components/css/breadcrumbs/breadcrumbs.js"
+export { breadcrumbs } from "./components/css/breadcrumbs/breadcrumbs.js"
+export type {
+  ButtonAttributes,
+  ButtonOptions,
+  ButtonVariant,
+} from "./components/css/button/button.js"
+export { button } from "./components/css/button/button.js"
+export type {
+  CardAttributes,
+  CardOptions,
+  CardVariant,
+} from "./components/css/card/card.js"
+export { card } from "./components/css/card/card.js"
+export type {
+  CheckboxAttributes,
+  CheckboxOptions,
+} from "./components/css/checkbox/checkbox.js"
+export { checkbox } from "./components/css/checkbox/checkbox.js"
+export type {
+  DividerAttributes,
+  DividerOptions,
+  DividerVariant,
+} from "./components/css/divider/divider.js"
+export { divider } from "./components/css/divider/divider.js"
+export type {
+  ErrorTextAttributes,
+  ErrorTextOptions,
+  ErrorTextVariant,
+} from "./components/css/error-text/error-text.js"
+export { errorText } from "./components/css/error-text/error-text.js"
+export type {
+  FieldsetAttributes,
+  FieldsetOptions,
+  LegendAttributes,
+  LegendOptions,
+} from "./components/css/fieldset/fieldset.js"
+export { fieldset, legend } from "./components/css/fieldset/fieldset.js"
+export type {
+  FileUploadAttributes,
+  FileUploadOptions,
+} from "./components/css/file-upload/file-upload.js"
+export { fileUpload } from "./components/css/file-upload/file-upload.js"
+export type {
+  HeadingAttributes,
+  HeadingOptions,
+  HeadingSize,
+} from "./components/css/heading/heading.js"
+export { heading } from "./components/css/heading/heading.js"
+export type {
+  HelpTextAttributes,
+  HelpTextOptions,
+  HelpTextVariant,
+} from "./components/css/help-text/help-text.js"
+export { helpText } from "./components/css/help-text/help-text.js"
+export type {
+  IconAttributes,
+  IconOptions,
+} from "./components/css/icon/icon.js"
+export { icon } from "./components/css/icon/icon.js"
+export type {
+  InputAttributes,
+  InputOptions,
+  InputType,
+} from "./components/css/input/input.js"
+export { input } from "./components/css/input/input.js"
+export type {
+  LabelAttributes,
+  LabelOptions,
+} from "./components/css/label/label.js"
+export { label } from "./components/css/label/label.js"
+export type { LinkAttributes, LinkOptions } from "./components/css/link/link.js"
+export { link } from "./components/css/link/link.js"
+export type {
+  ListAttributes,
+  ListOptions,
+  ListVariant,
+} from "./components/css/list/list.js"
+export { list } from "./components/css/list/list.js"
+export type { PaginationAttributes } from "./components/css/pagination/pagination.js"
+export { pagination } from "./components/css/pagination/pagination.js"
+export type {
+  ParagraphAttributes,
+  ParagraphOptions,
+  ParagraphSize,
+  ParagraphVariant,
+} from "./components/css/paragraph/paragraph.js"
+export { paragraph } from "./components/css/paragraph/paragraph.js"
+export type {
+  ProgressAttributes,
+  ProgressColor,
+  ProgressOptions,
+} from "./components/css/progress/progress.js"
+export { progress } from "./components/css/progress/progress.js"
+export type {
+  RadioAttributes,
+  RadioOptions,
+} from "./components/css/radio/radio.js"
+export { radio } from "./components/css/radio/radio.js"
+export type {
+  SearchAttributes,
+  SearchOptions,
+} from "./components/css/search/search.js"
+export { search } from "./components/css/search/search.js"
+export type {
+  NonDefaultSelectPicker,
+  SelectAttributes,
+  SelectOptions,
+  SelectPicker,
+} from "./components/css/select/select.js"
+export {
+  isSelectPicker,
+  select,
+  selectPickers,
+} from "./components/css/select/select.js"
+export * from "./components/css/shared.js"
+export type {
+  SkeletonAttributes,
+  SkeletonOptions,
+  SkeletonVariant,
+} from "./components/css/skeleton/skeleton.js"
+export { skeleton } from "./components/css/skeleton/skeleton.js"
+export type { SkipLinkAttributes } from "./components/css/skip-link/skip-link.js"
+export { skipLink } from "./components/css/skip-link/skip-link.js"
+export type {
+  SpinnerAttributes,
+  SpinnerOptions,
+  SpinnerSize,
+} from "./components/css/spinner/spinner.js"
+export { spinner } from "./components/css/spinner/spinner.js"
+export type { SrOnlyAttributes } from "./components/css/sr-only/sr-only.js"
+export { srOnly } from "./components/css/sr-only/sr-only.js"
+export type {
+  SwitchAttributes,
+  SwitchOptions,
+} from "./components/css/switch/switch.js"
+export { switchControl } from "./components/css/switch/switch.js"
+export type {
+  TableAttributes,
+  TableOptions,
+  TableSortAttributes,
+  TableSortDirection,
+  TableSortOptions,
+  TableVariant,
+} from "./components/css/table/table.js"
+export {
+  table,
+  tableSort,
+  tableSortDirections,
+} from "./components/css/table/table.js"
+export type {
+  TagAttributes,
+  TagOptions,
+  TagVariant,
+} from "./components/css/tag/tag.js"
+export { tag } from "./components/css/tag/tag.js"
+export type {
+  TextareaAttributes,
+  TextareaOptions,
+} from "./components/css/textarea/textarea.js"
+export { textarea } from "./components/css/textarea/textarea.js"
+export type { ToggleGroupAttributes } from "./components/css/toggle-group/toggle-group.js"
+export { toggleGroup } from "./components/css/toggle-group/toggle-group.js"
+export type { TooltipAttributes } from "./components/css/tooltip/tooltip.js"
+export { tooltip } from "./components/css/tooltip/tooltip.js"
+export type { LtEventMap } from "./components/events.js"
+export type {
+  DialogAttributes,
+  DialogOptions,
+} from "./components/frame/dialog/dialog.js"
+export { dialog } from "./components/frame/dialog/dialog.js"
+export * from "./components/frame/dialog/lt-dialog.js"
+export * from "./components/frame/error-summary/error-summary.js"
+export * from "./components/frame/error-summary/lt-error-summary.js"
+export * from "./components/frame/field/field-core.js"
+export * from "./components/frame/field/lt-field.js"
+export * from "./components/frame/popover/lt-popover.js"
+export * from "./components/frame/popover/popover.js"
+export * from "./components/frame/session-timeout/lt-session-timeout.js"
+export * from "./components/frame/session-timeout/session-timeout.js"
+export * from "./components/frame/suggestion/lt-suggestion.js"
+export * from "./components/frame/suggestion/suggestion.js"
+export * from "./components/frame/tabs/lt-tabs.js"
+export * from "./components/frame/tabs/tabs.js"
+export * from "./components/standalone/connection-status/connection-status.js"
+export * from "./components/standalone/connection-status/lt-connection-status.js"
+export * from "./components/standalone/toast/lt-toast.js"
+export * from "./components/standalone/toast/toast.js"
+export type { Attributes } from "./dom.js"
+export { setAttributes } from "./dom.js"
+export type { Lt } from "./lt.js"
+export { lt } from "./lt.js"
+export * from "./tokens/tokens.js"

package/src/jsx/react.ts

@@ -0,0 +1,212 @@
+import type { HTMLAttributes, RefAttributes } from "react"
+
+// The types of the events and tag names, so `querySelector("lt-dialog")` and
+// `addEventListener` are typed also for someone who only imports this entry
+// point. The file has no other import from the components, so without the
+// line neither `HTMLElementEventMap` nor `HTMLElementTagNameMap` was extended.
+export type { LtEventMap } from "../components/events.js"
+
+/**
+ * Types for the LO-TEK web components in JSX.
+ *
+ * Without them TypeScript does not know `<lt-field>` at all, and says
+ * "Property 'lt-field' does not exist on type JSX.IntrinsicElements". And the
+ * attributes are hyphenated strings without completion, so `described-by`
+ * and `server-controlled` are exactly where a typo is easy to make and hard
+ * to spot.
+ *
+ * Import once in the project, preferably from a `.d.ts` file so it does not
+ * end up in the bundle:
+ *
+ * ```ts
+ * // src/lotek.d.ts
+ * import "@lo-tek/interfaces/react-jsx"
+ * ```
+ *
+ * Astro does not need this: there `<lt-field>` is plain HTML, and no type
+ * check looks at the element name.
+ */
+
+/**
+ * Boolean attributes on web components.
+ *
+ * The type is `true | undefined`, not `boolean` and not `""`, and that is
+ * deliberate. React treats web components differently between versions, and
+ * only one pattern is right in both:
+ *
+ *     React 18 sets attributes          React 19 sets properties
+ *     open=""          works             never open
+ *     open={true}      works             works
+ *     open={false}     ALWAYS open       works
+ *     open={undefined} works             works
+ *
+ * React 18 stringifies to `open="false"`. The attribute then exists, and is
+ * therefore true. React 19 sets the property to `""`, which is falsy, and
+ * the setter in the component removes the attribute again.
+ *
+ * That is why the builder functions send `true` for a boolean attribute on a
+ * host, not the empty string. `data-*` is different: React passes those on
+ * as attributes in both versions, and there `""` is the canonical form.
+ *
+ * When you write it by hand, write `open={isOpen || undefined}`. The type
+ * here makes the two other variants compile errors instead of something you
+ * have to remember.
+ */
+type Flag = true | undefined
+
+/**
+ * The server decides the state in this element.
+ *
+ * The components set back what the user has done when a patch tears it away:
+ * the selected tab, the open popover, the expanded suggestion list. With this
+ * they do not, and each patch decides. Use it when the server should be able
+ * to move the tab itself, as in "go on to step 2".
+ */
+type ServerControlled = {
+  "server-controlled"?: Flag
+}
+
+/**
+ * The base shape of a web component in JSX.
+ *
+ * `HTMLAttributes` alone has no `ref`. It is in `RefAttributes`, and without
+ * it `<lt-toast ref={queue} />` was a type error, which is exactly the
+ * pattern the documentation recommends for calling `.show()` and `.hide()`.
+ * `key` comes the same way.
+ */
+type Host = HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement>
+
+type LtFieldAttributes = Host & {
+  disabled?: Flag
+  optional?: Flag
+  "described-by"?: string
+}
+
+/**
+ * `<lt-tabs>` has `server-controlled` and `activation`, and no `selected`.
+ *
+ * Which tab is selected is in the markup the server sent, as `aria-selected`
+ * on the tab and `hidden` on the panels. The component reads it from there
+ * instead of keeping a `selected` of its own, so the two can never disagree.
+ */
+type LtTabsAttributes = Host &
+  ServerControlled & {
+    /**
+     * `manual`: the arrow keys only move focus, and Enter or Space selects.
+     * Default: the arrow keys select straight away.
+     */
+    activation?: "manual" | "automatic"
+  }
+
+type LtErrorSummaryAttributes = Host & {
+  /**
+   * The box is hidden until there are errors to show.
+   *
+   * `HTMLAttributes` already has `hidden` as `boolean`, but on a web
+   * component the rule for `open` applies: React 18 writes `hidden={false}`
+   * as the attribute `hidden="false"`, and the box is then always hidden. So
+   * the type is `Flag` here too, and `hidden={hasErrors ? undefined : true}`
+   * is what compiles. `lt.errorSummary().host` sends it that way.
+   */
+  hidden?: Flag
+  /**
+   * Move focus here when the box appears. Default: on.
+   * Set `"false"` to turn it off.
+   */
+  "data-autofocus"?: "false" | "true"
+}
+
+type LtSuggestionAttributes = Host & {
+  /**
+   * Someone else has already filtered, so the component should not.
+   *
+   * The component hides an option when its text does not contain what is in
+   * the field. If you filter on something else, the two disagree, and then
+   * your filter should win. A React app that renders only the matches of a
+   * search that ignores diacritics is the most common case, alongside a
+   * Datastar app where the server sends the list again.
+   *
+   * The number of matches is announced whoever did the filtering.
+   */
+  prefiltered?: Flag
+  /** The announcement for zero matches, such as "No matches". */
+  "count-none"?: string
+  /** The announcement in the form `Intl.PluralRules` calls `zero`. `{n}` is the number. */
+  "count-zero"?: string
+  /** The announcement for one match, such as "{n} match". `{n}` is the number. */
+  "count-one"?: string
+  /** The announcement in the form `two`. `{n}` is the number. */
+  "count-two"?: string
+  /** The announcement in the form `few`. `{n}` is the number. */
+  "count-few"?: string
+  /** The announcement in the form `many`. `{n}` is the number. */
+  "count-many"?: string
+  /** The announcement for every other count, and the fallback. `{n}` is the number. */
+  "count-other"?: string
+} & ServerControlled
+
+type LtDialogAttributes = Host &
+  ServerControlled & {
+    /** The dialog is open. The component calls `showModal()`. */
+    open?: Flag
+  }
+
+type LtPopoverAttributes = Host &
+  ServerControlled & {
+    open?: Flag
+    /** Which edge the panel hangs from. */
+    placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end"
+  }
+
+type LtSessionTimeoutAttributes = Host & {
+  /** Seconds without activity before the warning appears. */
+  "warn-at"?: number | string
+  /** Seconds without activity before the session expires. */
+  "expires-at"?: number | string
+  /** Seconds between each `session-activity` while the user is active. */
+  "activity-interval"?: number | string
+}
+
+type LtConnectionStatusAttributes = Host & {
+  /** The text when the connection is lost. */
+  "offline-text"?: string
+  /** The text when it comes back. */
+  "online-text"?: string
+}
+
+type LtToastAttributes = Host & {
+  /** Milliseconds before the messages disappear. */
+  duration?: number
+  /** Text that says what the region is. */
+  label?: string
+  /** The screen reader name of the close button in each message. */
+  "close-label"?: string
+}
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "lt-dialog": LtDialogAttributes
+      "lt-error-summary": LtErrorSummaryAttributes
+      "lt-field": LtFieldAttributes
+      "lt-popover": LtPopoverAttributes
+      "lt-suggestion": LtSuggestionAttributes
+      "lt-tabs": LtTabsAttributes
+      "lt-session-timeout": LtSessionTimeoutAttributes
+      "lt-connection-status": LtConnectionStatusAttributes
+      "lt-toast": LtToastAttributes
+    }
+  }
+}
+
+export type {
+  LtConnectionStatusAttributes,
+  LtDialogAttributes,
+  LtErrorSummaryAttributes,
+  LtFieldAttributes,
+  LtPopoverAttributes,
+  LtSessionTimeoutAttributes,
+  LtSuggestionAttributes,
+  LtTabsAttributes,
+  LtToastAttributes,
+}

package/src/lt.ts

@@ -0,0 +1,192 @@
+import { accordion } from "./components/css/accordion/accordion.js"
+import { alert } from "./components/css/alert/alert.js"
+import { avatar } from "./components/css/avatar/avatar.js"
+import { badge } from "./components/css/badge/badge.js"
+import { breadcrumbs } from "./components/css/breadcrumbs/breadcrumbs.js"
+import { button } from "./components/css/button/button.js"
+import { card } from "./components/css/card/card.js"
+import { checkbox } from "./components/css/checkbox/checkbox.js"
+import { divider } from "./components/css/divider/divider.js"
+import { errorText } from "./components/css/error-text/error-text.js"
+import { fieldset, legend } from "./components/css/fieldset/fieldset.js"
+import { fileUpload } from "./components/css/file-upload/file-upload.js"
+import { heading } from "./components/css/heading/heading.js"
+import { helpText } from "./components/css/help-text/help-text.js"
+import { icon } from "./components/css/icon/icon.js"
+import { input } from "./components/css/input/input.js"
+import { label } from "./components/css/label/label.js"
+import { link } from "./components/css/link/link.js"
+import { list } from "./components/css/list/list.js"
+import { pagination } from "./components/css/pagination/pagination.js"
+import { paragraph } from "./components/css/paragraph/paragraph.js"
+import { progress } from "./components/css/progress/progress.js"
+import { radio } from "./components/css/radio/radio.js"
+import { search } from "./components/css/search/search.js"
+import { select } from "./components/css/select/select.js"
+import {
+  fieldStates,
+  isFieldState,
+  isRequiredMarker,
+  requiredMarkers,
+} from "./components/css/shared.js"
+import { skeleton } from "./components/css/skeleton/skeleton.js"
+import { skipLink } from "./components/css/skip-link/skip-link.js"
+import { spinner } from "./components/css/spinner/spinner.js"
+import { srOnly } from "./components/css/sr-only/sr-only.js"
+import { switchControl } from "./components/css/switch/switch.js"
+import { table, tableSort } from "./components/css/table/table.js"
+import { tag } from "./components/css/tag/tag.js"
+import { textarea } from "./components/css/textarea/textarea.js"
+import { toggleGroup } from "./components/css/toggle-group/toggle-group.js"
+import { tooltip } from "./components/css/tooltip/tooltip.js"
+import { dialog } from "./components/frame/dialog/dialog.js"
+import { errorSummary } from "./components/frame/error-summary/error-summary.js"
+import { computeFieldAttributes } from "./components/frame/field/field-core.js"
+import { popover } from "./components/frame/popover/popover.js"
+import { sessionTimeout } from "./components/frame/session-timeout/session-timeout.js"
+import { suggestion } from "./components/frame/suggestion/suggestion.js"
+import { tabs } from "./components/frame/tabs/tabs.js"
+import { connectionStatus } from "./components/standalone/connection-status/connection-status.js"
+import { toast } from "./components/standalone/toast/toast.js"
+import { setAttributes } from "./dom.js"
+
+/**
+ * The whole component API in one place.
+ *
+ * Each component is a function that takes an object of options and returns
+ * the attributes you spread onto the element:
+ *
+ * ```ts
+ * import { lt } from "@lo-tek/interfaces"
+ *
+ * <button {...lt.button({ variant: "secondary" })}>Save draft</button>
+ * <input {...lt.input({ type: "email", state: "invalid" })} />
+ * <span {...lt.badge({ color: "success" })}>Approved</span>
+ * ```
+ *
+ * The shape is the same for all of them, so you learn it once. Type `lt.` in
+ * the editor to see what exists; type `lt.button.` to see the allowed
+ * variants and the guard that validates values from outside.
+ *
+ * The return values are plain objects. That is why the same API works in
+ * React, Astro, Datastar and plain HTML.
+ */
+export const lt = {
+  accordion,
+  alert,
+  avatar,
+  badge,
+  breadcrumbs,
+  button,
+  card,
+  checkbox,
+  /**
+   * The bar that says the connection to the server is lost. The server
+   * cannot report that itself, so `<lt-connection-status>` creates the
+   * content.
+   */
+  connectionStatus,
+  dialog,
+  divider,
+  errorText,
+  /**
+   * The error summary above a form. The server writes the whole box, heading
+   * included, and `<lt-error-summary>` only moves focus.
+   */
+  errorSummary,
+  /**
+   * Connects the label, field, help text and error text.
+   *
+   * ```ts
+   * const field = lt.field({ id: "email", required: "text", help: true, error: true, invalid })
+   *
+   * <label {...field.label}>Email address</label>
+   * <input {...lt.input({ type: "email", state: field.state })} {...field.control} />
+   * <p {...lt.helpText()} {...field.help}>We send the receipt here.</p>
+   * <p {...lt.errorText()} {...field.error}>Enter a valid address.</p>
+   * ```
+   *
+   * The same calculation `<lt-field>` does, but as data, for markup created
+   * with JavaScript. Then no web component is needed.
+   */
+  field: computeFieldAttributes,
+  /** A group of controls that belong together. Its label is `lt.legend`. */
+  fieldset,
+  heading,
+  fileUpload,
+  helpText,
+  icon,
+  input,
+  label,
+  legend,
+  link,
+  list,
+  pagination,
+  paragraph,
+  /**
+   * The button and panel of a popover. `<lt-popover>` calculates the
+   * position, the server writes the wiring.
+   */
+  popover,
+  radio,
+  search,
+  select,
+  /**
+   * The warning that a signed-in session is about to expire. The countdown
+   * runs on the client's clock, so `<lt-session-timeout>` is responsible for
+   * the content.
+   */
+  sessionTimeout,
+  skeleton,
+  skipLink,
+  progress,
+  spinner,
+  /** Text only screen readers get. Requires `sr-only.css`. */
+  srOnly,
+  /**
+   * The field and the suggestion list. `<lt-suggestion>` handles the
+   * keyboard and the filtering, the server writes the markup.
+   */
+  suggestion,
+  /** On and off. Named `switchControl` when you import it directly. */
+  switch: switchControl,
+  /**
+   * A tab list with panels. The server writes the links, ids and classes;
+   * `<lt-tabs>` adds the roles, the selection and the arrow keys.
+   */
+  tabs,
+  /**
+   * The toast region. Sets `data-ignore-morph`, because `<lt-toast>` creates
+   * and removes its messages inside it.
+   */
+  toast,
+  toggleGroup,
+  tooltip,
+  table,
+  /**
+   * The header and button in a sortable column. `aria-sort` on the `<th>` is
+   * the state, and the arrow is drawn from it. The sorting is up to the app.
+   */
+  tableSort,
+  tag,
+  textarea,
+
+  /**
+   * Applies an attribute set to an element in the plain DOM.
+   *
+   * In JSX you spread the object. Without JSX this function does the job,
+   * and cleans up what the builder function manages from the previous state.
+   * Several sets are passed separately:
+   * `lt.setAttributes(field, lt.input(), wiring.control)`.
+   */
+  setAttributes,
+
+  /** The validation states shared by input, textarea and select. */
+  states: fieldStates,
+  isState: isFieldState,
+  /** The ways a required field can be marked. */
+  markers: requiredMarkers,
+  isMarker: isRequiredMarker,
+} as const
+
+export type Lt = typeof lt