@vastare/fundatio 0.1.0

package/src/elements/text/blockquote/index.ts

@@ -0,0 +1,203 @@
+/**
+ * Fundatio Design Foundation: Blockquote element helpers.
+ *
+ * @remarks
+ * The blockquote element (`<blockquote>`) represents a section that is quoted
+ * from another source.
+ *
+ * Best-practice guidance:
+ * - Use `<blockquote>` for longer, block-level quotations.
+ * - Use `<q>` for short, inline quotations.
+ * - If you provide a citation URL, set the `cite` attribute, but also consider
+ *   providing a visible citation in content (e.g. a link or a `<cite>` element),
+ *   since many user agents do not surface `cite` automatically.
+ * - Avoid presentational attributes. Use CSS for styling.
+ *
+ * Element-specific attributes:
+ * - `cite`: A URL for the source of the quotation (when available).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create block quotes 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.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote
+ *
+ * @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.
+ *
+ * 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 block quotes.
+ *
+ * @category Constants
+ */
+export const BLOCKQUOTE_TAG = 'blockquote' as const;
+
+/**
+ * A CSS selector targeting blockquote elements.
+ *
+ * @category Constants
+ */
+export const BLOCKQUOTE_SELECTOR = 'blockquote';
+
+/**
+ * Attribute bag for blockquote creation/enhancement.
+ *
+ * @remarks
+ * Blockquote accepts standard HTML global attributes and one element-specific
+ * attribute:
+ * - `cite`: A URL pointing to the quoted source (when available).
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria}.
+ *
+ * Security note:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style}.
+ *
+ * @category Attributes
+ */
+export type BlockquoteAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Citation URL for the source of the quote.
+   *
+   * @remarks
+   * This maps to the `cite` attribute. When present, it should be a valid URL.
+   * Consider also including a visible citation in the document content.
+   */
+  cite?: string;
+
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link BlockquoteAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The blockquote attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: BlockquoteAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, cite, ...rest } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  // Map element-specific attribute(s) into the escape hatch.
+  if (typeof cite === 'string' && cite.length > 0) {
+    mapped.attrs = { ...(rest.attrs ?? {}), cite };
+  }
+
+  if (!aria) return mapped;
+
+  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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...mapped, aria: mappedAria } : mapped;
+}
+
+/**
+ * Create a blockquote element with optional text content and attributes.
+ *
+ * @remarks
+ * - 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.
+ *
+ * Note: `<blockquote>` typically contains flow content (e.g. paragraphs). This
+ * helper supports a simple `text` convenience for cases where plain text is
+ * sufficient; consumers can still append richer child nodes afterwards.
+ *
+ * @param text - Optional text content for the blockquote.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<blockquote>` element.
+ *
+ * @example
+ * ```ts
+ * import { createBlockquote } from "@Vastare/Fundatio/elements/text/blockquote";
+ *
+ * const q = createBlockquote("To be, or not to be...", {
+ *   cite: "https://example.com/source",
+ *   className: "quote",
+ *   aria: { label: "Quotation" }
+ * });
+ *
+ * document.body.appendChild(q);
+ * ```
+ *
+ * @category DOM
+ */
+export function createBlockquote(
+  text?: string,
+  attrs?: BlockquoteAttrs,
+): ElementOf<typeof BLOCKQUOTE_TAG> {
+  return createElement(BLOCKQUOTE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance blockquote 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 enhanceBlockquotes(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for blockquote.
+  void root;
+}

package/src/elements/text/hr/hr.scss

@@ -0,0 +1,50 @@
+/**
+ * Fundatio Design Foundation: HR Element
+ *
+ * Thematic Break (`hr`)
+ *
+ * Baseline reset + subtle, brand-aligned default rule.
+ *
+ * This module:
+ * - Normalizes cross-browser UA differences for `<hr>`
+ * - Preserves semantic separation with a predictable visual rule
+ * - Uses low-specificity selectors (`:where()`)
+ * - Brands using Fundatio PostCSS variables (spacing + rule colour)
+ *
+ * References (2025+):
+ * - MDN: `<hr>` semantics and usage :contentReference[oaicite:0]{index=0}
+ * - Modern reset guidance and normalization context :contentReference[oaicite:1]{index=1}
+ * - MDN logical properties (flow-relative spacing) :contentReference[oaicite:2]{index=2}
+ */
+
+:where(hr) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+
+  // Normalize legacy UA quirks (historically present in normalize-style baselines).
+  // Ensures consistent rendering across engines.
+  box-sizing: content-box;
+  height: 0;
+  overflow: visible;
+
+  // Remove UA borders so we can define a single, predictable rule.
+  border: 0;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned default rule
+   -------------------------------------------------------------------------- */
+
+  // Provide a subtle thematic break line.
+  border-top: 1px solid var(--lg-colour-grey-tint-40);
+
+  /* --------------------------------------------------------------------------
+   - Spacing
+   -------------------------------------------------------------------------- */
+
+  // Default separation, using flow-relative logical properties.
+  margin-block: var(--lg-typography-spacing-base-margin-bottom);
+  margin-inline: 0;
+}

package/src/elements/text/hr/index.ts

@@ -0,0 +1,161 @@
+/**
+ * Fundatio Design Foundation: Hr element helpers.
+ *
+ * @remarks
+ * The hr element (`<hr>`) represents a thematic break between paragraph-level
+ * elements (e.g. a shift of topic or scene).
+ *
+ * Best-practice guidance:
+ * - Use `<hr>` for semantic separation of content, not for visual decoration.
+ * - Avoid obsolete presentational attributes (e.g. `align`, `size`, `width`, `noshade`);
+ *   use CSS instead.
+ * - Prefer native semantics. Only set `role` when you have a specific, justified reason.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create thematic breaks in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createVoidElement, 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 thematic breaks.
+ *
+ * @category Constants
+ */
+export const HR_TAG = 'hr' as const;
+
+/**
+ * A CSS selector targeting hr elements.
+ *
+ * @category Constants
+ */
+export const HR_SELECTOR = 'hr';
+
+/**
+ * Attribute bag for hr creation/enhancement.
+ *
+ * @remarks
+ * Hr 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 HrAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link HrAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The hr attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: HrAttrs): 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 an hr element with optional global attributes.
+ *
+ * @remarks
+ * - `<hr>` is a void element and must not carry text content.
+ * - 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 attrs - Optional attributes to apply.
+ * @returns The created `<hr>` element.
+ *
+ * @example
+ * Create and append a thematic break:
+ * ```ts
+ * import { createHr } from "@Vastare/Fundatio/elements/text/hr";
+ *
+ * document.body.appendChild(createHr({ className: "divider" }));
+ * ```
+ *
+ * @category DOM
+ */
+export function createHr(attrs?: HrAttrs): ElementOf<typeof HR_TAG> {
+  return createVoidElement(HR_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance hr 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 enhanceHrs(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for hr.
+  void root;
+}

package/src/elements/text/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Text element factories.
+ *
+ * Provides framework-agnostic factory functions for common text and
+ * text-adjacent grouping elements.
+ *
+ * These factories:
+ * - Create semantic HTML text elements using Fundatio's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Apply sensible fallbacks where required by the HTML specification.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/text
+ * @since 1.0.0
+ */
+
+/**
+ * `<p>` element factory namespace.
+ *
+ * Represents a paragraph of text (phrasing content).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p
+ */
+export * as paragraph from './paragraph';
+
+/**
+ * `<hr>` element factory namespace.
+ *
+ * Represents a thematic break between paragraph-level elements.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr
+ */
+export * as hr from './hr';
+
+/**
+ * `<pre>` element factory namespace.
+ *
+ * Represents preformatted text where whitespace is significant.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre
+ */
+export * as pre from './pre';
+
+/**
+ * `<blockquote>` element factory namespace.
+ *
+ * Represents a section quoted from another source (an extended quotation).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote
+ */
+export * as blockquote from './blockquote';
+
+/**
+ * `<address>` element factory namespace.
+ *
+ * Represents contact information for a person, people, or an organization.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address
+ */
+export * as address from './address';

package/src/elements/text/paragraph/index.ts

@@ -0,0 +1,179 @@
+/**
+ * Fundatio Design Foundation: Paragraph (`p`) element helpers.
+ *
+ * @remarks
+ * The paragraph element (`<p>`) represents a paragraph: a structural grouping of
+ * related phrasing content. It is a block-level element in HTML rendering
+ * contexts, but its meaning is semantic, not visual.
+ *
+ * Best-practice guidance:
+ * - Use `<p>` for paragraphs of text (phrasing content).
+ * - Do not use `<p>` as a generic layout container. Prefer semantic grouping
+ *   elements (e.g. `<section>`, `<article>`) or non-semantic `<div>` only when
+ *   semantics do not apply.
+ * - Avoid nesting block-level content inside `<p>`. In HTML parsing, a `<p>`
+ *   element will auto-close when certain elements are encountered.
+ * - Avoid obsolete attributes like `align`; use CSS instead.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create paragraphs 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.
+ *
+ * References:
+ * - MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p
+ * - WHATWG: https://html.spec.whatwg.org/multipage/grouping-content.html#the-p-element
+ *
+ * @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`.
+   *
+   * @remarks
+   * Prefer `labelledby` when a visible labeling element exists.
+   */
+  label?: string;
+
+  /**
+   * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+   */
+  labelledby?: string;
+
+  /**
+   * Decorative/hidden hint, mapped to `aria-hidden`.
+   *
+   * @remarks
+   * Generally avoid hiding meaningful text from assistive technology.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for paragraphs.
+ *
+ * @category Constants
+ */
+export const P_TAG = 'p' as const;
+
+/**
+ * A CSS selector targeting paragraph elements.
+ *
+ * @category Constants
+ */
+export const P_SELECTOR = 'p';
+
+/**
+ * Attribute bag for paragraph creation/enhancement.
+ *
+ * @remarks
+ * Paragraph 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 PAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link PAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The paragraph attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: PAttrs): 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 paragraph element with optional text content and global attributes.
+ *
+ * @remarks
+ * - 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 paragraph.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<p>` element.
+ *
+ * @example
+ * Create and append a paragraph:
+ * ```ts
+ * import { createP } from "@Vastare/Fundatio/elements/text/p";
+ *
+ * document.body.appendChild(
+ *   createP("Hello.", { className: "lead", id: "intro" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createP(text?: string, attrs?: PAttrs): ElementOf<typeof P_TAG> {
+  return createElement(P_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance paragraph 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 enhancePs(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for paragraphs.
+  void root;
+}

package/src/elements/text/paragraph/paragraph.scss

@@ -0,0 +1,49 @@
+/**
+ * Fundatio Design Foundation: Paragraph Element
+ *
+ * Paragraph (`p`)
+ *
+ * Baseline + light element-layer styling.
+ *
+ * This module:
+ * - Ensures consistent cross-browser baseline for paragraphs
+ * - Applies modern reset principles (2025+)
+ * - Adds sensible defaults and brand-aligned typography tokens
+ * - Respects UA defaults where still useful
+ *
+ * @module
+ * @group  elements.text.p
+ * @access public
+ * @since  1.0.0
+ */
+
+:where(p) {
+  // Display: ensure block-level consistency
+  display: block;
+
+  // Typography: robustness & branding
+  font-family: var(--lg-typography-font-families-base-font-family);
+  font-size: var(--lg-typography-font-sizes-base-font-size);
+  font-weight: var(--lg-typography-formatting-base-font-weight);
+  line-height: var(--lg-typography-formatting-base-line-height);
+  color: var(--lg-theme-base-colours-base-font-color);
+
+  // Browser reset / normalization
+  margin: 0; // remove UA default margins for tighter control
+  padding: 0; // ensure no unexpected paddings
+  overflow-wrap: break-word; // avoid overflow inconsistencies across rendering engines :contentReference[oaicite:1]{index=1}
+  text-wrap: pretty; // modern text wrapping where supported :contentReference[oaicite:2]{index=2}
+
+  // Inherit spelling and linebreak behavior
+  text-indent: inherit;
+  white-space: normal;
+
+  // Sizing: consistent for responsive typography
+  max-width: 100%;
+
+  // Reset browser list-style fallbacks
+  list-style-type: none;
+
+  // Accessibility improvement: ensure baseline readability
+  hyphens: auto;
+}