@lnpg/pkgn-sol 1.0.0-beta.0

package/dist/types/elements/responsive/track/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * pkgn-sol Design Foundation: Track element helpers.
+ *
+ * @remarks
+ * The track element (`<track>`) provides external timed text tracks for media
+ * elements such as `<video>` and `<audio>`. Tracks can represent:
+ * - subtitles
+ * - captions
+ * - descriptions
+ * - chapters
+ * - metadata
+ *
+ * Best-practice guidance:
+ * - Use `<track>` for WebVTT (and similar timed text) resources that accompany media.
+ * - Use `kind` to declare the track purpose (subtitles, captions, etc.).
+ * - Use `label` for a user-facing title shown in media track selection UIs.
+ * - Use `srclang` to declare the track language (BCP 47 tag).
+ * - If `kind="subtitles"`, user agents/spec require `srclang` to be defined.
+ *
+ * Attribute behavior notes:
+ * - `default` is a boolean attribute. When present, it indicates this track
+ *   should be enabled if user preferences do not indicate a better choice.
+ *
+ * pkgn-sol keeps the API small and framework-agnostic:
+ * - Attributes are routed through pkgn-sol's hardened DOM helpers.
+ * - Unsafe attributes (inline event handlers, raw style) are blocked centrally.
+ * - 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/track
+ * @see https://html.spec.whatwg.org/multipage/media.html#the-track-element
+ *
+ * @module
+ * @category Elements
+ */
+import { 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;
+};
+/**
+ * Allowed values for the `kind` attribute on `<track>`.
+ *
+ * @remarks
+ * This follows the HTML living standard's enumerated states.
+ *
+ * @category Attributes
+ */
+export type TrackKind = 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+/**
+ * The semantic tag name for track.
+ *
+ * @category Constants
+ */
+export declare const TRACK_TAG: "track";
+/**
+ * A CSS selector targeting track elements.
+ *
+ * @category Constants
+ */
+export declare const TRACK_SELECTOR = "track";
+/**
+ * Attribute bag for track creation/enhancement.
+ *
+ * @remarks
+ * Track is a void element and must not carry text content or child nodes.
+ *
+ * Track accepts standard HTML global attributes plus track-specific attributes:
+ * - `kind`
+ * - `src`
+ * - `srclang`
+ * - `label`
+ * - `default` (boolean attribute)
+ *
+ * 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 TrackAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * The type of text track.
+     */
+    kind?: TrackKind;
+    /**
+     * The URL of the timed text track resource (commonly a `.vtt` file).
+     */
+    src?: string;
+    /**
+     * The language of the text track, as a BCP 47 language tag.
+     *
+     * @remarks
+     * If `kind` is `subtitles`, user agents/spec require `srclang` to be defined.
+     */
+    srclang?: string;
+    /**
+     * User-visible label for the track (typically shown in media UI menus).
+     */
+    label?: string;
+    /**
+     * Marks this track as the default if user preferences do not indicate another.
+     *
+     * @remarks
+     * This maps to the `default` boolean attribute (presence-based).
+     */
+    default?: boolean;
+};
+/**
+ * Create a track element and apply attributes.
+ *
+ * @remarks
+ * Track is a void element:
+ * - It must not have text content.
+ * - It must not have child nodes.
+ *
+ * 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 attrs - Optional attributes to apply.
+ * @returns The created `<track>` element.
+ *
+ * @example
+ * ```ts
+ * import { createTrack } from "@lnpg/pkgn-sol/elements/responsive/track";
+ *
+ * const t = createTrack({
+ *   kind: "subtitles",
+ *   src: "/captions/en.vtt",
+ *   srclang: "en",
+ *   label: "English",
+ *   default: true
+ * });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createTrack(attrs?: TrackAttrs): ElementOf<typeof TRACK_TAG>;
+/**
+ * Enhance track 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 declare function enhanceTracks(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/responsive/track/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/responsive/track/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAiDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAE3E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}

package/dist/types/elements/table/caption/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * pkgn-sol Design Foundation: Caption element helpers.
+ *
+ * @remarks
+ * The caption element (`<caption>`) provides a title (caption) for its parent
+ * `<table>`. It is an important accessibility feature because it gives the table
+ * an accessible name or description when authored appropriately. :contentReference[oaicite:1]{index=1}
+ *
+ * Best-practice guidance:
+ * - Use `<caption>` to describe the purpose of the table and help users decide
+ *   whether to read it. :contentReference[oaicite:2]{index=2}
+ * - Place `<caption>` as the first child of the `<table>` in source order. :contentReference[oaicite:3]{index=3}
+ * - Keep the caption concise but meaningful. For complex tables, captions can be
+ *   supplemented with additional explanatory text near the table (outside the
+ *   caption) when necessary. :contentReference[oaicite:4]{index=4}
+ * - Avoid deprecated presentational attributes (e.g. legacy `align`) and use CSS instead. :contentReference[oaicite:5]{index=5}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<caption>` elements 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.
+ *
+ * @module
+ * @category Elements
+ */
+import { 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 caption elements.
+ *
+ * @category Constants
+ */
+export declare const CAPTION_TAG: "caption";
+/**
+ * A CSS selector targeting caption elements.
+ *
+ * @category Constants
+ */
+export declare const CAPTION_SELECTOR = "caption";
+/**
+ * Attribute bag for caption creation/enhancement.
+ *
+ * @remarks
+ * Caption 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.
+ *
+ * Security notes:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style} instead.
+ *
+ * @category Attributes
+ */
+export type CaptionAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create a caption 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 caption.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<caption>` element.
+ *
+ * @example
+ * Create and prepend a caption to a table:
+ * ```ts
+ * import { createCaption } from "@lnpg/pkgn-sol/elements/table/caption";
+ *
+ * const table = document.createElement("table");
+ * table.prepend(createCaption("Quarterly results"));
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createCaption(text?: string, attrs?: CaptionAttrs): ElementOf<typeof CAPTION_TAG>;
+/**
+ * Enhance caption 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 declare function enhanceCaptions(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/table/caption/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/table/caption/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAG,SAAkB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACrD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEhG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGjE"}

package/dist/types/elements/table/col/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * pkgn-sol Design Foundation: Col element helpers.
+ *
+ * @remarks
+ * The col element (`<col>`) represents one or more columns in a table, and is
+ * used to apply presentation (typically CSS) to columns as a group.
+ *
+ * Best-practice guidance:
+ * - Use `<col>` only inside a `<colgroup>`.
+ * - Use `<col>` for column-level styling (widths, background, etc.), not layout hacks.
+ * - Don't rely on `<col>` for semantics or accessibility. Use proper table
+ *   structure (`<caption>`, `<th>`, `scope`/`headers`) for accessible data tables.
+ * - Avoid obsolete presentational attributes; prefer CSS.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<col>` elements 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.
+ *
+ * References:
+ * - MDN: `<col>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/col
+ * - WHATWG HTML: Tables: https://html.spec.whatwg.org/multipage/tables.html
+ *
+ * @module
+ * @category Elements
+ */
+import { 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 table column definitions.
+ *
+ * @category Constants
+ */
+export declare const COL_TAG: "col";
+/**
+ * A CSS selector targeting col elements.
+ *
+ * @category Constants
+ */
+export declare const COL_SELECTOR = "col";
+/**
+ * Attribute bag for col creation/enhancement.
+ *
+ * @remarks
+ * `<col>` supports standard HTML global attributes and one primary element
+ * attribute: `span`.
+ *
+ * `span` specifies how many consecutive columns this `<col>` applies to.
+ * If omitted, browsers treat it as `1`.
+ *
+ * pkgn-sol supports a structured ARIA input for common ARIA fields, mapped into
+ * {@link GlobalAttrs.aria}.
+ *
+ * @category Attributes
+ */
+export type ColAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Number of consecutive columns this `<col>` element applies to.
+     *
+     * @remarks
+     * Must be a positive integer greater than zero. If omitted, the browser default
+     * is `1`.
+     */
+    span?: number;
+};
+/**
+ * Create a col element (`<col>`) and apply global attributes.
+ *
+ * @remarks
+ * `<col>` is a void element. It does not accept text content or children.
+ *
+ * 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 attrs - Optional attributes to apply.
+ * @returns The created `<col>` element.
+ *
+ * @example
+ * Create a `<col>` that spans 2 columns:
+ * ```ts
+ * import { createCol } from "@lnpg/pkgn-sol/elements/table/col";
+ *
+ * const col = createCol({ span: 2, className: "numeric" });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createCol(attrs?: ColAttrs): ElementOf<typeof COL_TAG>;
+/**
+ * Enhance col elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `0.1.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceCols(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/table/col/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/table/col/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAG,KAAc,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACjD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AA6CF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,OAAO,CAAC,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG7D"}

package/dist/types/elements/table/colgroup/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * pkgn-sol Design Foundation: Colgroup element helpers.
+ *
+ * @remarks
+ * The colgroup element (`<colgroup>`) represents a group of one or more columns
+ * in a table and is primarily used to apply presentation (not structure) to
+ * entire columns (typically via CSS). :contentReference[oaicite:1]{index=1}
+ *
+ * Best-practice guidance:
+ * - Use `<colgroup>` (and optionally `<col>`) to apply column-level styling
+ *   without repeating styles across cells.
+ * - Place `<colgroup>` inside a `<table>`, after any `<caption>` and before
+ *   `<thead>`, `<tbody>`, `<tfoot>`, or `<tr>`. :contentReference[oaicite:2]{index=2}
+ * - Use the `span` attribute only when the `<colgroup>` contains no `<col>`
+ *   children; otherwise, define spans via `<col>` elements. :contentReference[oaicite:3]{index=3}
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create `<colgroup>` elements 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.
+ *
+ * @module
+ * @category Elements
+ */
+import { 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 colgroup elements.
+ *
+ * @category Constants
+ */
+export declare const COLGROUP_TAG: "colgroup";
+/**
+ * A CSS selector targeting colgroup elements.
+ *
+ * @category Constants
+ */
+export declare const COLGROUP_SELECTOR = "colgroup";
+/**
+ * Attribute bag for colgroup creation/enhancement.
+ *
+ * @remarks
+ * Colgroup elements accept standard HTML global attributes, plus:
+ * - `span`: the number of consecutive columns in the group (when no `<col>`
+ *   children are present). :contentReference[oaicite:4]{index=4}
+ *
+ * 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.
+ *
+ * Security notes:
+ * - Inline event handler attributes (e.g. `onclick`) are blocked by `dom.ts`.
+ * - The raw `style` attribute is blocked; use {@link GlobalAttrs.style} instead.
+ *
+ * @category Attributes
+ */
+export type ColgroupAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Number of consecutive columns spanned by this column group.
+     *
+     * @remarks
+     * This should be a positive integer. The HTML spec clamps values above 1000
+     * and treats invalid/zero values as `1` in the table model. pkgn-sol does not
+     * attempt to emulate the full table model at runtime; it sets the attribute
+     * when you provide a valid positive integer. :contentReference[oaicite:5]{index=5}
+     *
+     * Note: Not permitted when the `<colgroup>` contains one or more `<col>`
+     * elements. pkgn-sol does not enforce child-structure rules; consumers control
+     * their DOM trees. :contentReference[oaicite:6]{index=6}
+     */
+    span?: number;
+};
+/**
+ * Create a colgroup element with global attributes.
+ *
+ * @remarks
+ * - `<colgroup>` should not contain text content; pkgn-sol does not accept a `text`
+ *   argument for this factory.
+ * - 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 attrs - Optional attributes to apply.
+ * @returns The created `<colgroup>` element.
+ *
+ * @example
+ * Create a colgroup that spans two columns:
+ * ```ts
+ * import { createColgroup } from "@lnpg/pkgn-sol/elements/table/colgroup";
+ *
+ * const colgroup = createColgroup({ span: 2, className: "cols" });
+ * table.appendChild(colgroup);
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createColgroup(attrs?: ColgroupAttrs): ElementOf<typeof COLGROUP_TAG>;
+/**
+ * Enhance colgroup 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 declare function enhanceColgroups(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/table/colgroup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/table/colgroup/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACtD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAiEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC,OAAO,YAAY,CAAC,CAEpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGlE"}