@lo-tek/interfaces 0.0.0 → 0.38.0

package/src/dom.ts

@@ -0,0 +1,185 @@
+/**
+ * Applying the attributes to an element in the plain DOM.
+ *
+ * In JSX you spread the object straight onto the element. Without JSX you
+ * would have to loop through it yourself, and take care to remove attributes
+ * from the previous state. When a field goes from invalid to valid, the
+ * builder function leaves out `data-state`, and a `setAttribute` alone would
+ * have left the old value in place.
+ */
+
+import { managedNames } from "./components/css/shared.js"
+
+/**
+ * What gets cleaned up for a set without a builder function behind it.
+ *
+ * A handwritten or spread set is not in the map of what it manages, and then
+ * the `data-*` names are the only ones the function can safely remove: they
+ * belong to the system. A set straight from a builder function does not use
+ * this list. It cleans up exactly what the builder function manages, so
+ * `lt.popover().trigger` on a secondary button leaves `data-variant` alone.
+ */
+const SAFE_FOR_UNKNOWN = [
+  "data-variant",
+  "data-state",
+  "data-color",
+  "data-size",
+  "data-picker",
+  "data-required",
+  "data-optional",
+  "data-interactive",
+  "data-hoverable",
+  "data-selectable",
+  "data-autofocus",
+] as const
+
+/**
+ * Names that are never removed, not even when the builder function manages
+ * them.
+ *
+ * `id` and `for` are connections other elements point to. `lt.errorSummary()`
+ * takes an optional `id`, and a call without it removed the id the consumer
+ * had written on the box: every link and every `aria-*` pointing there broke.
+ */
+const NEVER_REMOVED: readonly string[] = ["id", "for"]
+
+let warnedAboutUnknownSet = false
+
+/** The classes that belong to the system. The consumer's classes are kept. */
+const IS_SYSTEM_CLASS = /^lt-/
+
+/**
+ * The values a builder function can output.
+ *
+ * `true` and `false` are included because several of them are boolean HTML
+ * attributes: `disabled` on a switch, `multiple` on a file field, `hidden` on
+ * an error text. In HTML such an attribute is true as long as it exists,
+ * whatever its value, so `true` is set as the empty string and `false`
+ * removes it.
+ */
+export type Attributes = Record<string, string | boolean | undefined>
+
+/**
+ * Sets the attributes from an `lt` function on an element.
+ *
+ * ```ts
+ * import { lt } from "@lo-tek/interfaces"
+ *
+ * const field = document.querySelector("input")
+ * lt.setAttributes(field, lt.input({ type: "email", state: "invalid" }))
+ * ```
+ *
+ * Call it again to change state. What the builder function manages and is
+ * not in the new set is removed, and the `lt-` classes are replaced. A
+ * builder function manages the attributes it has an option for:
+ * `lt.spinner()` has `label`, and so manages `role` and `aria-label`. What it
+ * has no option for stays as it is: `lt.button()` has never written
+ * `disabled`, so a disabled button is still disabled afterwards. `id` and
+ * `for` are never removed.
+ *
+ * When two sets go on the same element, pass them separately, not spread
+ * together:
+ *
+ * ```ts
+ * lt.setAttributes(field, lt.input({ type: "email" }), wiring.control)
+ * ```
+ *
+ * A spread object is a new object, and then the function does not know which
+ * builder function it came from. It is set correctly, but only `data-*` is
+ * cleaned up. An explicit `false` in a handwritten set removes the attribute.
+ *
+ * It accepts `null`, and then does nothing. `document.querySelector()`
+ * returns `Element | null`, so without that every call site in a `strict` app
+ * would need a guard or an exclamation mark around a lookup that almost
+ * always succeeds. It is the same trade-off as `element?.classList`.
+ */
+export function setAttributes(
+  element: Element | null | undefined,
+  ...sets: Attributes[]
+): void {
+  if (!element || sets.length === 0) return
+
+  const merged: Attributes = {}
+  const removable = new Set<string>()
+  const classes: string[] = []
+
+  for (const set of sets) {
+    const names = managedNames(set)
+    if (names) {
+      for (const name of names) removable.add(name)
+    } else {
+      for (const name of SAFE_FOR_UNKNOWN) removable.add(name)
+      warnAboutUnknownSet(set)
+    }
+    for (const [name, value] of Object.entries(set)) {
+      if (name === "class") {
+        if (typeof value === "string") classes.push(...value.split(/\s+/))
+      } else if (value === false) {
+        // An explicit `false` in a handwritten set is a request.
+        merged[name] = false
+        removable.add(name)
+      } else if (value !== undefined) {
+        // `undefined` does not override an earlier set: the builder functions
+        // drop such keys themselves, and a handwritten set must not be able to
+        // take `aria-invalid` from `lt.input()` by naming it without a value.
+        merged[name] = value
+      }
+    }
+  }
+  for (const name of NEVER_REMOVED) removable.delete(name)
+
+  if (classes.length > 0) {
+    const ownClasses = [...element.classList].filter(
+      (token) => !IS_SYSTEM_CLASS.test(token),
+    )
+    // `setAttribute` and not `className`: on an `<svg>`, `className` is a
+    // read-only `SVGAnimatedString`, and `lt.icon()` belongs on an svg.
+    element.setAttribute(
+      "class",
+      [...new Set([...classes, ...ownClasses])].filter(Boolean).join(" "),
+    )
+  }
+
+  for (const name of removable) {
+    if (name === "class") continue
+    setOrRemove(element, name, merged[name])
+  }
+
+  for (const [name, value] of Object.entries(merged)) {
+    if (removable.has(name)) continue
+    if (value === undefined || value === false) continue
+    element.setAttribute(name, value === true ? "" : value)
+  }
+}
+
+/**
+ * Warns, once, about a set that looks like two spread together.
+ *
+ * `{ ...lt.input(), ...field.control }` is set correctly, but is a new object
+ * without a builder function behind it. The next call then does not remove
+ * `aria-invalid` when the field becomes valid, and nothing else would have
+ * said so.
+ */
+function warnAboutUnknownSet(set: Attributes): void {
+  if (warnedAboutUnknownSet) return
+  if (typeof set.class !== "string" || !/(^|\s)lt-/.test(set.class)) return
+  warnedAboutUnknownSet = true
+  console.warn(
+    "lt.setAttributes(): the set does not come straight from a builder " +
+      "function, so only the data attributes are cleaned up. Pass the sets " +
+      "separately instead of spreading them: " +
+      "lt.setAttributes(element, lt.input(), field.control).",
+  )
+}
+
+function setOrRemove(
+  element: Element,
+  name: string,
+  value: string | boolean | undefined,
+): void {
+  if (value === undefined || value === false) {
+    element.removeAttribute(name)
+  } else {
+    element.setAttribute(name, value === true ? "" : value)
+  }
+}

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,
+}