@vastare/fundatio 0.1.0

package/src/elements/form/button/index.ts

@@ -0,0 +1,335 @@
+/**
+ * Fundatio Design Foundation: Button element helpers.
+ *
+ * @remarks
+ * The button element (`<button>`) is an interactive control that users can
+ * activate via mouse, keyboard, touch, or assistive technology. :contentReference[oaicite:5]{index=5}
+ *
+ * Best-practice guidance:
+ * - Prefer native `<button>` semantics over non-semantic elements with `role="button"`.
+ * - Provide an accessible name via visible text or ARIA labelling.
+ * - Avoid placing interactive content inside a button (nested links/inputs/etc.).
+ * - In forms, explicitly set a button `type` to avoid accidental submissions.
+ *   In HTML, the default `type` is effectively `"submit"` in many form contexts. :contentReference[oaicite:6]{index=6}
+ *
+ * Fundatio-specific conventions:
+ * - Defaults `type` to `"button"` unless the caller explicitly sets `type`
+ *   (via the typed `type` field or via the raw `attrs` escape hatch).
+ * - Applies global attributes via Fundatio's hardened DOM helpers (`dom.ts`),
+ *   which block inline event handler attributes (e.g. `onclick`) and the raw
+ *   `style` attribute string.
+ * - Supports a small structured ARIA input to reduce typo-based ARIA bugs.
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type AttrValue, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset mapped into {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+  /**
+   * Accessible label, mapped to `aria-label`.
+   */
+  label?: string;
+
+  /**
+   * ID reference(s) to labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * Allowed `type` values for `<button>`.
+ *
+ * @remarks
+ * HTML supports `submit`, `reset`, and `button`. :contentReference[oaicite:7]{index=7}
+ *
+ * @category Attributes
+ */
+export type ButtonType = 'submit' | 'reset' | 'button';
+
+/**
+ * Allowed `formenctype` values for submit buttons.
+ *
+ * @category Attributes
+ */
+export type ButtonFormEnctype =
+  | 'application/x-www-form-urlencoded'
+  | 'multipart/form-data'
+  | 'text/plain';
+
+/**
+ * Allowed `formmethod` values for submit buttons.
+ *
+ * @remarks
+ * `dialog` is supported for form submission to a dialog in HTML. :contentReference[oaicite:8]{index=8}
+ *
+ * @category Attributes
+ */
+export type ButtonFormMethod = 'get' | 'post' | 'dialog';
+
+/**
+ * Allowed `popovertargetaction` values for popover trigger buttons.
+ *
+ * @remarks
+ * Mirrors the `popovertargetaction` attribute. :contentReference[oaicite:9]{index=9}
+ *
+ * @category Attributes
+ */
+export type PopoverTargetAction = 'toggle' | 'show' | 'hide';
+
+/**
+ * The semantic tag name for buttons.
+ *
+ * @category Constants
+ */
+export const BUTTON_TAG = 'button' as const;
+
+/**
+ * A CSS selector targeting button elements.
+ *
+ * @category Constants
+ */
+export const BUTTON_SELECTOR = 'button';
+
+/**
+ * Attribute bag for button creation/enhancement.
+ *
+ * @remarks
+ * `<button>` supports global attributes plus button/form-associated attributes.
+ * This type models the most commonly used attributes in a typed way, while still
+ * providing {@link GlobalAttrs.attrs} as an escape hatch (validated by `dom.ts`).
+ *
+ * Notes:
+ * - `type` defaults to `"button"` in Fundatio to avoid accidental form submission.
+ * - Boolean attributes are applied by presence (empty string) when `true`.
+ * - `command` and `commandfor` are part of the HTML Invoker Commands model. :contentReference[oaicite:10]{index=10}
+ *
+ * @category Attributes
+ */
+export type ButtonAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * The button type. Fundatio defaults to `"button"` when not provided.
+   */
+  type?: ButtonType;
+
+  /**
+   * The button name (used during form submission).
+   */
+  name?: string;
+
+  /**
+   * The button value (used during form submission).
+   */
+  value?: string;
+
+  /**
+   * Disables the button when true.
+   */
+  disabled?: boolean;
+
+  /**
+   * Autofocus hint.
+   */
+  autofocus?: boolean;
+
+  /**
+   * Associates the button with a form element by ID.
+   */
+  form?: string;
+
+  /**
+   * Overrides the form `action` for submit buttons.
+   */
+  formAction?: string;
+
+  /**
+   * Overrides the form encoding type for submit buttons.
+   */
+  formEnctype?: ButtonFormEnctype;
+
+  /**
+   * Overrides the form HTTP method for submit buttons.
+   */
+  formMethod?: ButtonFormMethod;
+
+  /**
+   * When true, prevents constraint validation on submission.
+   */
+  formNoValidate?: boolean;
+
+  /**
+   * Overrides the form target for submission.
+   *
+   * @remarks
+   * Can be a special keyword like `_blank` or a named browsing context.
+   */
+  formTarget?: string;
+
+  /**
+   * ID of the popover element this button targets.
+   */
+  popoverTarget?: string;
+
+  /**
+   * Action to perform on the targeted popover.
+   */
+  popoverTargetAction?: PopoverTargetAction;
+
+  /**
+   * Invoker Commands: the command name.
+   */
+  command?: string;
+
+  /**
+   * Invoker Commands: the element ID to invoke/control.
+   */
+  commandFor?: string;
+};
+
+/**
+ * Normalize {@link ButtonAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @remarks
+ * This follows the same pattern used by other attribute-rich modules (e.g. iframe):
+ * - Start with any caller-provided raw attrs escape hatch.
+ * - Apply typed attributes without overriding explicit raw attributes.
+ * - Map structured ARIA into {@link GlobalAttrs.aria}.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ButtonAttrs): GlobalAttrs {
+  const {
+    aria,
+    type,
+    name,
+    value,
+    disabled,
+    autofocus,
+    form,
+    formAction,
+    formEnctype,
+    formMethod,
+    formNoValidate,
+    formTarget,
+    popoverTarget,
+    popoverTargetAction,
+    command,
+    commandFor,
+    ...rest
+  } = attrs ?? {};
+
+  // Start with any caller-provided attrs escape hatch (still validated by dom.ts).
+  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };
+
+  // Helper: only set if caller didn't already set the raw attribute explicitly.
+  const setIfUnset = (key: string, v: AttrValue | undefined): void => {
+    if (v === undefined) return;
+    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;
+    mergedAttrs[key] = v;
+  };
+
+  // Fundatio safety: default to type="button" unless caller explicitly overrides it.
+  setIfUnset('type', type ?? 'button');
+
+  setIfUnset('name', name);
+  setIfUnset('value', value);
+  setIfUnset('form', form);
+  setIfUnset('formaction', formAction);
+  setIfUnset('formenctype', formEnctype);
+  setIfUnset('formmethod', formMethod);
+  setIfUnset('formtarget', formTarget);
+  setIfUnset('popovertarget', popoverTarget);
+  setIfUnset('popovertargetaction', popoverTargetAction);
+  setIfUnset('command', command);
+  setIfUnset('commandfor', commandFor);
+
+  // Boolean attributes are represented by presence. We set empty-string when true.
+  if (disabled === true) setIfUnset('disabled', '');
+  if (autofocus === true) setIfUnset('autofocus', '');
+  if (formNoValidate === true) setIfUnset('formnovalidate', '');
+
+  const mapped: GlobalAttrs = { ...rest, attrs: mergedAttrs };
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+  if (aria) {
+    if (typeof aria.label === 'string') mappedAria.label = aria.label;
+    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+  }
+
+  if (Object.keys(mappedAria).length > 0) {
+    mapped.aria = mappedAria;
+  }
+
+  // If mergedAttrs ended up empty, avoid attaching it.
+  if (Object.keys(mergedAttrs).length === 0) {
+    const { attrs: _unused, ...withoutAttrs } = mapped;
+    return withoutAttrs;
+  }
+
+  return mapped;
+}
+
+/**
+ * Create a button element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Fundatio defaults `type` to `"button"` to reduce accidental form submissions. :contentReference[oaicite:11]{index=11}
+ * - Global attributes are applied via Fundatio's shared DOM helper, including security
+ *   guards that block inline event handler attributes (e.g. `onclick`) and raw
+ *   `style` attribute strings.
+ *
+ * @param text - Optional text content for the button.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<button>` element.
+ *
+ * @example
+ * ```ts
+ * import { createButton } from "@Vastare/Fundatio/elements/form/button";
+ *
+ * document.body.appendChild(createButton("Save", { className: "btn" }));
+ * ```
+ *
+ * @category DOM
+ */
+export function createButton(text?: string, attrs?: ButtonAttrs): ElementOf<typeof BUTTON_TAG> {
+  return createElement(BUTTON_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance button elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `1.0.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceButtons(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for button.
+  void root;
+}

package/src/elements/form/datalist/datalist.scss

@@ -0,0 +1,40 @@
+/**
+ * Fundatio Design Foundation: Datalist Element
+ *
+ * Datalist (`datalist`)
+ *
+ * Baseline hygiene only.
+ *
+ * Notes:
+ * - `<datalist>` provides predefined options for an `<input list="...">`.
+ * - Rendering is UA-defined; avoid attempting presentation resets.
+ * - Keep structural defaults and inheritance safe when shipped standalone.
+ *
+ * References (2025+):
+ * - MDN: `<datalist>` element reference (2025)
+ *
+ * @module
+ * @group  elements.form.datalist
+ * @access public
+ * @since  1.0.0
+ */
+
+:where(datalist) {
+  /* --------------------------------------------------------------------------
+   - Baseline
+   -------------------------------------------------------------------------- */
+
+  // Do not force display; UA controls how datalist participates in rendering.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Defensive inheritance (harmless even if element isn't visually rendered).
+  font-family: inherit;
+  font-size: inherit;
+  font-style: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  color: inherit;
+  background-color: transparent;
+}

package/src/elements/form/datalist/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Fundatio Design Foundation: Datalist element helpers.
+ *
+ * @remarks
+ * The datalist element (`<datalist>`) contains a set of `<option>` elements that
+ * represent permissible or recommended values for an associated form control
+ * (most commonly an `<input>`), connected via the input's `list` attribute.
+ *
+ * Best-practice guidance:
+ * - Pair a `<datalist>` with an `<input>` using a stable, unique `id` on the
+ *   datalist and a matching `list` attribute on the input.
+ * - Use `<datalist>` for suggestions, not strict validation. If users must pick
+ *   from a fixed set, prefer `<select>`.
+ * - Populate suggestions using descendant `<option>` elements, typically with
+ *   `value` attributes.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<datalist>` elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * Attributes:
+ * - `<datalist>` supports global attributes only (no element-specific content
+ *   attributes).
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by Fundatio's `dom.ts` helpers which
+ *   block inline event handler attributes (e.g. `onclick`) and raw `style`
+ *   attribute injection (use the `style` object field instead).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/datalist
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs (e.g. `lable`).
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+  /**
+   * Accessible label, mapped to `aria-label`.
+   */
+  label?: string;
+
+  /**
+   * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for datalist.
+ *
+ * @category Constants
+ */
+export const DATALIST_TAG = 'datalist' as const;
+
+/**
+ * A CSS selector targeting datalist elements.
+ *
+ * @category Constants
+ */
+export const DATALIST_SELECTOR = 'datalist';
+
+/**
+ * Attribute bag for datalist creation/enhancement.
+ *
+ * @remarks
+ * Datalist elements accept standard HTML global attributes.
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing Fundatio's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type DatalistAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link DatalistAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The datalist attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DatalistAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, ...rest } = attrs;
+
+  if (!aria) return rest;
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (typeof aria.label === 'string') mappedAria.label = aria.label;
+  if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+  if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create a datalist element with optional text content and global attributes.
+ *
+ * @remarks
+ * While `<datalist>` is typically populated with `<option>` children, this helper
+ * follows Fundatio's consistent "optional text" factory signature for non-void elements.
+ *
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via Fundatio's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional text content for the datalist (rare, but supported).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<datalist>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDatalist } from "@Vastare/Fundatio/elements/form/datalist";
+ *
+ * const dl = createDatalist(undefined, { id: "city-list" });
+ * document.body.appendChild(dl);
+ * ```
+ *
+ * @category DOM
+ */
+export function createDatalist(
+  text?: string,
+  attrs?: DatalistAttrs,
+): ElementOf<typeof DATALIST_TAG> {
+  return createElement(DATALIST_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance datalist elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `1.0.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceDatalists(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for datalist.
+  void root;
+}

package/src/elements/form/fieldset/fieldset.scss

@@ -0,0 +1,46 @@
+/**
+ * Fundatio Design Foundation: Fieldset Element
+ *
+ * Grouping container (`fieldset`)
+ *
+ * Token-driven, light baseline.
+ *
+ * This module:
+ * - Normalizes UA border/padding/margin quirks
+ * - Prevents unexpected min-inline-size behavior
+ * - Preserves grouping semantics (no layout patterns imposed)
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.form.fieldset
+ * @access public
+ * @since  1.0.0
+ */
+
+:where(fieldset) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize UA spacing and border chrome.
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // UA often applies a min-inline-size. Neutralize so it behaves like a normal block.
+  min-inline-size: 0;
+
+  // Predictable sizing.
+  box-sizing: border-box;
+  max-width: 100%;
+
+  // Typography inheritance so it ships standalone.
+  font-family: var(--lg-typography-font-families-base-font-family, inherit);
+  font-size: var(--lg-typography-font-sizes-base-font-size, inherit);
+  font-weight: var(--lg-typography-formatting-base-font-weight, inherit);
+  line-height: var(--lg-typography-formatting-base-line-height, inherit);
+  color: var(--lg-theme-base-colours-base-font-color, inherit);
+  background-color: transparent;
+}