@lnpg/pkgn-sol 1.0.0-beta.0

package/src/elements/interactive/dialog/index.ts

@@ -0,0 +1,219 @@
+/**
+ * pkgn-sol Design Foundation: Dialog element helpers.
+ *
+ * @remarks
+ * The dialog element (`<dialog>`) represents a modal or non-modal dialog box
+ * (e.g. a confirm prompt, inspector, or subwindow).
+ *
+ * Best-practice guidance:
+ * - Prefer using the platform APIs:
+ *   - `dialog.showModal()` for modal dialogs
+ *   - `dialog.show()` for non-modal dialogs
+ *   - `dialog.close()` to close, optionally supplying a return value
+ * - Provide an accessible name for the dialog content (e.g. heading + `aria-labelledby`
+ *   or `aria-label` when appropriate).
+ * - Ensure the dialog contains an obvious close mechanism.
+ * - Avoid relying solely on adding/removing `open`; prefer the element's methods
+ *   for correct focus and modal behavior.
+ *
+ * Attributes (element-specific):
+ * - `open` (boolean): when present, the dialog is active and available for interaction.
+ * - `closedBy` (enumerated): maps to the `closedby` content attribute (spec-defined).
+ *
+ * Security:
+ * - Global attribute escape hatches are guarded by pkgn-sol'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/dialog
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol 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 dialog.
+ *
+ * @category Constants
+ */
+export const DIALOG_TAG = 'dialog' as const;
+
+/**
+ * A CSS selector targeting dialog elements.
+ *
+ * @category Constants
+ */
+export const DIALOG_SELECTOR = 'dialog';
+
+/**
+ * Values supported by the `closedby` content attribute.
+ *
+ * @remarks
+ * This is a newer platform feature that specifies which user actions can close
+ * the dialog automatically.
+ *
+ * - `any`: close requests or clicks outside close the dialog.
+ * - `closerequest`: close requests close the dialog.
+ * - `none`: no user actions automatically close the dialog.
+ *
+ * @category Types
+ */
+export type DialogClosedBy = 'any' | 'closerequest' | 'none';
+
+/**
+ * Attribute bag for dialog creation/enhancement.
+ *
+ * @remarks
+ * Dialog elements accept standard HTML global attributes plus a small set of
+ * dialog-specific content attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type DialogAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Whether the dialog is open (active).
+   *
+   * @remarks
+   * Maps to the `open` boolean attribute.
+   *
+   * Prefer controlling visibility via the native methods (`showModal`, `show`,
+   * `close`) when possible.
+   */
+  open?: boolean;
+
+  /**
+   * Control user actions that can close the dialog.
+   *
+   * @remarks
+   * Maps to the `closedby` content attribute.
+   */
+  closedBy?: DialogClosedBy;
+};
+
+/**
+ * Normalize {@link DialogAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The dialog attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: DialogAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const { aria, open, closedBy, ...rest } = attrs;
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  const extra: NonNullable<GlobalAttrs['attrs']> = { ...(mapped.attrs ?? {}) };
+
+  if (open === true) extra.open = true;
+
+  if (closedBy === 'any' || closedBy === 'closerequest' || closedBy === 'none') {
+    extra.closedby = closedBy;
+  }
+
+  if (Object.keys(extra).length > 0) {
+    mapped.attrs = extra;
+  }
+
+  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;
+
+  // Only attach `aria` if something was actually defined.
+  const hasMappedAria = Object.keys(mappedAria).length > 0;
+
+  return hasMappedAria ? { ...mapped, aria: mappedAria } : mapped;
+}
+
+/**
+ * Create a dialog element with optional text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol'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 dialog.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<dialog>` element.
+ *
+ * @example
+ * ```ts
+ * import { createDialog } from "@lnpg/pkgn-sol/elements/interactive/dialog";
+ *
+ * const d = createDialog("Hello", { open: true });
+ * ```
+ *
+ * @category DOM
+ */
+export function createDialog(text?: string, attrs?: DialogAttrs): ElementOf<typeof DIALOG_TAG> {
+  return createElement(DIALOG_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance dialog elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.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 enhanceDialogs(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for dialog.
+  void root;
+}

package/src/elements/interactive/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Interactive element factories.
+ *
+ * Provides framework-agnostic factory functions for interactive HTML elements
+ * that expose built-in browser behaviors such as disclosure widgets and modal
+ * dialogs.
+ *
+ * These factories:
+ * - Create semantic interactive structures using pkgn-sol's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Preserve correct accessibility semantics and relationships.
+ * - Prevent unsafe attribute injection.
+ *
+ * The elements in this module provide native interactivity that browsers
+ * understand without requiring JavaScript frameworks.
+ *
+ * @module elements/interactive
+ * @since 0.1.0
+ */
+
+/**
+ * `<details>` element factory namespace.
+ *
+ * Represents a disclosure widget that users can open and close to reveal
+ * additional information.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
+ */
+export * as details from './details';
+
+/**
+ * `<dialog>` element factory namespace.
+ *
+ * Represents a dialog box or interactive component such as a modal window,
+ * alert, or confirmation interface.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+export * as dialog from './dialog';
+
+/**
+ * `<summary>` element factory namespace.
+ *
+ * Represents the summary or visible heading for a `<details>` disclosure
+ * widget. Clicking the summary toggles the details content.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary
+ */
+export * as summary from './summary';

package/src/elements/interactive/summary/index.ts

@@ -0,0 +1,161 @@
+/**
+ * pkgn-sol Design Foundation: Summary element helpers.
+ *
+ * @remarks
+ * The summary element (`<summary>`) provides the visible label for a parent
+ * `<details>` disclosure widget. Activating (clicking / pressing Enter) on the
+ * `<summary>` toggles the open state of the parent `<details>` element.
+ *
+ * Best-practice guidance:
+ * - Use `<summary>` only as the first child of a `<details>` element.
+ * - Use clear, concise text so the disclosure purpose is obvious.
+ * - Prefer semantic content inside `<summary>`; avoid overly complex interactive
+ *   children inside the summary label.
+ *
+ * pkgn-sol notes:
+ * - This module is framework-agnostic and has no side effects.
+ * - Global attributes are applied via pkgn-sol's shared DOM helper, which blocks:
+ *   - inline event handler attributes (e.g. `onclick`)
+ *   - raw `style` attribute injection (use the `style` object instead)
+ * - Text passed to factories is assigned via `textContent` (never `innerHTML`).
+ *
+ * References:
+ * - MDN: `<summary>` element
+ * - WHATWG HTML: `<details>` content model and summary semantics
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol 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 summary.
+ *
+ * @category Constants
+ */
+export const SUMMARY_TAG = 'summary' as const;
+
+/**
+ * A CSS selector targeting summary elements.
+ *
+ * @category Constants
+ */
+export const SUMMARY_SELECTOR = 'summary';
+
+/**
+ * Attribute bag for summary creation/enhancement.
+ *
+ * @remarks
+ * `<summary>` supports standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type SummaryAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link SummaryAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The summary attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: SummaryAttrs): 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;
+
+  const hasMapped = Object.keys(mappedAria).length > 0;
+
+  return hasMapped ? { ...rest, aria: mappedAria } : rest;
+}
+
+/**
+ * Create a summary element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol'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 summary.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<summary>` element.
+ *
+ * @example
+ * ```ts
+ * import { createSummary } from "@lnpg/pkgn-sol/elements/interactive/summary";
+ *
+ * const s = createSummary("More details");
+ * ```
+ *
+ * @category DOM
+ */
+export function createSummary(text?: string, attrs?: SummaryAttrs): ElementOf<typeof SUMMARY_TAG> {
+  return createElement(SUMMARY_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance summary elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.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
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export function enhanceSummaries(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for summary.
+  void root;
+}

package/src/elements/interactive/summary/summary.scss

@@ -0,0 +1,48 @@
+/**
+ * pkgn-sol Design Foundation: Summary Element
+ *
+ * Disclosure summary (`summary`)
+ *
+ * Baseline reset + light usability normalization.
+ *
+ * This module:
+ * - Preserves the spec default `display: list-item` so the disclosure marker remains
+ * - Normalizes spacing for consistent rendering
+ * - Adds a safe affordance cursor (interactive control)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.interactive.summary
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(summary) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Spec default: list-item (enables the disclosure marker).
+  display: list-item;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  // Keep the marker, but normalize its positioning for predictable spacing.
+  list-style-position: outside;
+
+  // Interactive affordance (without touching focus styles).
+  cursor: pointer;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  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;
+}

package/src/elements/layout/article/article.scss

@@ -0,0 +1,42 @@
+/**
+ * pkgn-sol Design Foundation: Article Element
+ *
+ * Self-contained composition (`article`)
+ *
+ * Baseline reset + light branding.
+ *
+ * This module:
+ * - Normalizes UA spacing
+ * - Keeps `<article>` purely structural (no layout opinions)
+ * - Applies base typography tokens so it can ship standalone
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.layout.article
+ * @access public
+ * @since  0.1.0
+ */
+
+:where(article) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  display: block;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  box-sizing: border-box;
+  max-width: 100%;
+
+  /* --------------------------------------------------------------------------
+   - Brand-aligned baseline typography (standalone-safe)
+   -------------------------------------------------------------------------- */
+
+  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;
+}

package/src/elements/layout/article/index.ts

@@ -0,0 +1,169 @@
+/**
+ * pkgn-sol Design Foundation: Article element helpers.
+ *
+ * @remarks
+ * The article element (`<article>`) represents a self-contained composition in a
+ * document, page, application, or site that is intended to be independently
+ * distributable or reusable (e.g. syndication).
+ *
+ * Best-practice guidance:
+ * - Use `<article>` for content that makes sense on its own (blog post, news item,
+ *   forum post, comment, product card, etc.).
+ * - Prefer `<section>` for thematic grouping that is not independently distributable.
+ * - Articles commonly include a heading (h1-h6) in their content, but this module
+ *   does not enforce structure at runtime.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create article sections in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if pkgn-sol 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/article
+ * @see https://html.spec.whatwg.org/multipage/sections.html#the-article-element
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by pkgn-sol 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 article.
+ *
+ * @category Constants
+ */
+export const ARTICLE_TAG = 'article' as const;
+
+/**
+ * A CSS selector targeting article elements.
+ *
+ * @category Constants
+ */
+export const ARTICLE_SELECTOR = 'article';
+
+/**
+ * Attribute bag for article creation/enhancement.
+ *
+ * @remarks
+ * Article elements accept standard HTML global attributes.
+ *
+ * pkgn-sol also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing pkgn-sol's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type ArticleAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+};
+
+/**
+ * Normalize {@link ArticleAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The article attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: ArticleAttrs): 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 article element with optional text content and global attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - Global attributes are applied via pkgn-sol'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 article.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<article>` element.
+ *
+ * @example
+ * ```ts
+ * import { createArticle } from "@lnpg/pkgn-sol/elements/layout/article";
+ *
+ * document.body.appendChild(
+ *   createArticle(undefined, { className: "post", aria: { label: "Blog post" } })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createArticle(text?: string, attrs?: ArticleAttrs): ElementOf<typeof ARTICLE_TAG> {
+  return createElement(ARTICLE_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance article elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.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 enhanceArticles(root: ParentNode = document): void {
+  // v0.1.0: no runtime behavior for article.
+  void root;
+}