@malva-ui/core 0.1.12

package/docs/ai/timeline.md

@@ -0,0 +1,320 @@
+# Library: timeline
+
+## Overview
+
+`@malva-ui/core/timeline` provides a vertical timeline component for visualising ordered sequences of events. It is composed of two components (`mlv-timeline`, `mlv-timeline-item`) and two slot directives (`[mlvTimelineItemIcon]`, `[mlvTimelineItemMeta]`).
+
+The timeline renders as an ordered list (`role="list"`) with each item as a `role="listitem"`. Items use a 3-column CSS grid: left content column, centre spine (node circle + connector line), and right content column. The `direction` input on each item controls which column shows the content, enabling alternating left/right layouts. The connector line on the last child is hidden automatically via the CSS `:last-child` selector — no Angular logic required.
+
+---
+
+## Public API
+
+| Export                     | Kind      | Description                                                       |
+| -------------------------- | --------- | ----------------------------------------------------------------- | ------------------- | --------- | --------- | -------- | ----------- |
+| `MlvTimeline`              | Component | Container — `mlv-timeline`                                        |
+| `MlvTimelineItem`          | Component | Single event entry — `mlv-timeline-item`                          |
+| `MlvTimelineItemIcon`      | Directive | Template slot for the node icon — `[mlvTimelineItemIcon]`         |
+| `MlvTimelineItemMeta`      | Directive | Template slot for metadata badges/chips — `[mlvTimelineItemMeta]` |
+| `MlvTimelineItemTone`      | Type      | `MlvTone                                                          | 'default'` (`'info' | 'success' | 'warning' | 'danger' | 'default'`) |
+| `MlvTimelineItemDirection` | Type      | `'left'                                                           | 'right'`            |
+
+---
+
+## Components
+
+### `MlvTimeline`
+
+**Selector:** `mlv-timeline`
+**Change Detection:** `OnPush`
+**Encapsulation:** `ViewEncapsulation.None`
+
+The container component. Renders as a flex column list (`display: flex; flex-direction: column`). Content-projects `mlv-timeline-item` children directly with `<ng-content />`.
+
+#### Host Bindings
+
+| Binding | Value                     |
+| ------- | ------------------------- |
+| `class` | `'mlv-timeline'` (static) |
+| `role`  | `'list'` (static)         |
+
+#### Inputs
+
+None.
+
+#### Outputs
+
+None.
+
+#### SCSS
+
+BEM block: `.mlv-timeline`
+
+```scss
+.mlv-timeline {
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+}
+```
+
+---
+
+### `MlvTimelineItem`
+
+**Selector:** `mlv-timeline-item`
+**Change Detection:** `OnPush`
+**Encapsulation:** `ViewEncapsulation.None`
+**Imports:** `NgTemplateOutlet`
+
+A single event entry rendered in a 3-column CSS grid. The node circle sits in the centre column; content appears in the left or right column depending on `direction()`. The connector line extends below the node and is hidden on `:last-child` via CSS.
+
+#### Host Bindings
+
+| Binding                                     | Value                            |
+| ------------------------------------------- | -------------------------------- |
+| `class`                                     | `'mlv-timeline-item'` (static)   |
+| `role`                                      | `'listitem'` (static)            |
+| `[class]`                                   | `"mlv-timeline-item--" + tone()` |
+| `[class.mlv-timeline-item--direction-left]` | `direction() === 'left'`         |
+
+#### Inputs
+
+| Name        | Type                       | Default     | Required | Description                                                                                                          |
+| ----------- | -------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `title`     | `string`                   | —           | Yes      | Heading text for this timeline event.                                                                                |
+| `timestamp` | `string`                   | `''`        | No       | Date/time string rendered in a `<time>` element. Use ISO 8601 for machine-readable precision.                        |
+| `tone`      | `MlvTimelineItemTone`      | `'default'` | No       | Accent colour of the node circle.                                                                                    |
+| `direction` | `MlvTimelineItemDirection` | `'right'`   | No       | Which column shows the content. `'right'` = node left, content right (default). `'left'` = content left, node right. |
+
+#### Outputs
+
+None.
+
+#### Content Children (protected)
+
+| Name       | Type                                | Description                                                                                                  |
+| ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `_iconRef` | `contentChild(MlvTimelineItemIcon)` | Optional icon/avatar template for the node circle. When absent, the node renders as a plain coloured circle. |
+| `_metaRef` | `contentChild(MlvTimelineItemMeta)` | Optional metadata template (badges, chips) rendered in the item header.                                      |
+
+#### Template Summary
+
+The template is a 3-column grid:
+
+1. **Left column** (`.mlv-timeline-item__col--left`) — renders content when `direction() === 'left'`:
+   - `.mlv-timeline-item__header`: title span, optional `<time>` timestamp, optional meta slot.
+   - `.mlv-timeline-item__description`: default `<ng-content />` for the event description.
+
+2. **Centre spine** (`.mlv-timeline-item__spine`) — always rendered:
+   - `.mlv-timeline-item__node-circle`: coloured circle (tone-driven). Renders `_iconRef` template if present (`aria-hidden="true"` on the icon wrapper).
+   - `.mlv-timeline-item__connector`: vertical line below the node (`aria-hidden="true"`); hidden on `:last-child`.
+
+3. **Right column** (`.mlv-timeline-item__col--right`) — renders content when `direction() === 'right'` (default):
+   - Same header + description structure as the left column.
+
+The header layout for `direction === 'left'` uses `flex-direction: row-reverse` so the timestamp appears before the title visually.
+
+#### SCSS
+
+BEM block: `.mlv-timeline-item`
+
+| Class                                | Description                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| `.mlv-timeline-item`                 | Block root; 3-column CSS grid (`1fr <node-size> 1fr`)                      |
+| `.mlv-timeline-item__col`            | Grid column wrapper                                                        |
+| `.mlv-timeline-item__col--left`      | Left text column (`text-align: right`)                                     |
+| `.mlv-timeline-item__col--right`     | Right text column (`text-align: left`)                                     |
+| `.mlv-timeline-item__spine`          | Centre column flex container (node + connector)                            |
+| `.mlv-timeline-item__node-circle`    | Coloured circle; size: `--mlv-tli-node-size` (2.5rem)                      |
+| `.mlv-timeline-item__node-icon`      | Icon wrapper inside node circle (`aria-hidden`)                            |
+| `.mlv-timeline-item__connector`      | Vertical line; `min-height: --mlv-spacing-8`; hidden on `:last-child`      |
+| `.mlv-timeline-item__content`        | Padded content area; `padding-bottom: --mlv-spacing-8`; 0 on `:last-child` |
+| `.mlv-timeline-item__content--left`  | Right-aligns text for left-direction items                                 |
+| `.mlv-timeline-item__header`         | Flex row (title + timestamp + meta); `gap: 0.5rem`                         |
+| `.mlv-timeline-item__title`          | Semibold heading; `--mlv-font-size-m`                                      |
+| `.mlv-timeline-item__timestamp`      | Muted secondary text; `--mlv-typography-ui-s`; `white-space: nowrap`       |
+| `.mlv-timeline-item__meta`           | Inline-flex container for badge/chip slots                                 |
+| `.mlv-timeline-item__description`    | Secondary-colour body text; `--mlv-font-size-m`                            |
+| `.mlv-timeline-item--default`        | Node colour: `--mlv-border-normal`                                         |
+| `.mlv-timeline-item--success`        | Node colour: `--mlv-background-success-1`                                  |
+| `.mlv-timeline-item--warning`        | Node colour: `--mlv-background-warning-1`                                  |
+| `.mlv-timeline-item--danger`         | Node colour: `--mlv-background-danger-1`                                   |
+| `.mlv-timeline-item--info`           | Node colour: `--mlv-background-info-1`                                     |
+| `.mlv-timeline-item--direction-left` | Header flex-direction reversed                                             |
+
+CSS custom properties (component-scoped):
+
+| Variable                    | Default                    | Description                                          |
+| --------------------------- | -------------------------- | ---------------------------------------------------- |
+| `--mlv-tli-node-bg`         | `var(--mlv-border-normal)` | Node circle background; overridden by tone modifiers |
+| `--mlv-tli-node-size`       | `2.5rem`                   | Node circle diameter                                 |
+| `--mlv-tli-connector-width` | `0.125rem`                 | Connector line thickness                             |
+
+---
+
+## Directives
+
+### `MlvTimelineItemIcon`
+
+**Selector:** `[mlvTimelineItemIcon]`
+
+Template slot directive used inside `<mlv-timeline-item>` to provide a custom icon or avatar for the node circle. When present, its template replaces the default plain-circle indicator.
+
+**Usage:** wrap content in `<ng-template mlvTimelineItemIcon>`.
+
+| Member        | Type                     | Description                                                                |
+| ------------- | ------------------------ | -------------------------------------------------------------------------- |
+| `templateRef` | `TemplateRef` (injected) | Template reference rendered inside the node circle via `ngTemplateOutlet`. |
+
+---
+
+### `MlvTimelineItemMeta`
+
+**Selector:** `[mlvTimelineItemMeta]`
+
+Template slot directive for supplementary metadata (badges, chips, status indicators) displayed in the timeline item header alongside the title and timestamp.
+
+**Usage:** wrap content in `<ng-template mlvTimelineItemMeta>`.
+
+| Member        | Type                     | Description                                                                       |
+| ------------- | ------------------------ | --------------------------------------------------------------------------------- |
+| `templateRef` | `TemplateRef` (injected) | Template reference rendered in `.mlv-timeline-item__meta` via `ngTemplateOutlet`. |
+
+---
+
+## Interfaces & Types
+
+### `MlvTimelineItemTone`
+
+```typescript
+type MlvTimelineItemTone = MlvTone | 'default'; // 'info' | 'success' | 'warning' | 'danger' | 'default'
+```
+
+Controls the node circle accent colour via BEM modifier and CSS custom property override.
+
+| Value       | Node colour token            |
+| ----------- | ---------------------------- |
+| `'default'` | `--mlv-border-normal`        |
+| `'success'` | `--mlv-background-success-1` |
+| `'warning'` | `--mlv-background-warning-1` |
+| `'danger'`  | `--mlv-background-danger-1`  |
+| `'info'`    | `--mlv-background-info-1`    |
+
+### `MlvTimelineItemDirection`
+
+```typescript
+type MlvTimelineItemDirection = 'left' | 'right';
+```
+
+Controls which column (left or right of the centre spine) shows the event content.
+
+| Value               | Content column | BEM modifier                         |
+| ------------------- | -------------- | ------------------------------------ |
+| `'right'` (default) | Right column   | (none)                               |
+| `'left'`            | Left column    | `.mlv-timeline-item--direction-left` |
+
+---
+
+## Usage Examples
+
+### Basic timeline
+
+```html
+<mlv-timeline>
+  <mlv-timeline-item title="Submitted" timestamp="Mar 24, 2025" tone="info"> Form submitted by the user. </mlv-timeline-item>
+  <mlv-timeline-item title="Under Review" timestamp="Mar 25, 2025" tone="warning"> Awaiting manager approval. </mlv-timeline-item>
+  <mlv-timeline-item title="Approved" timestamp="Mar 26, 2025" tone="success"> Request approved and completed. </mlv-timeline-item>
+</mlv-timeline>
+```
+
+### Custom icon in the node circle
+
+```html
+<mlv-timeline>
+  <mlv-timeline-item title="Deployed" timestamp="2025-03-26T10:00:00" tone="success">
+    <ng-template mlvTimelineItemIcon>
+      <svg lucideRocket [size]="16" />
+    </ng-template>
+    Release v2.0.0 was deployed to production.
+  </mlv-timeline-item>
+  <mlv-timeline-item title="Rolled back" timestamp="2025-03-27T08:30:00" tone="danger">
+    <ng-template mlvTimelineItemIcon>
+      <svg lucideRotateCcw [size]="16" />
+    </ng-template>
+    Rollback initiated due to critical bug.
+  </mlv-timeline-item>
+</mlv-timeline>
+```
+
+### Metadata slot (badge/chip in header)
+
+```html
+<mlv-timeline>
+  <mlv-timeline-item title="Code Review" timestamp="Mar 25, 2025">
+    <ng-template mlvTimelineItemMeta>
+      <mlv-badge color="warning">Pending</mlv-badge>
+    </ng-template>
+    Awaiting code review from the team.
+  </mlv-timeline-item>
+  <mlv-timeline-item title="Merged" timestamp="Mar 26, 2025" tone="success">
+    <ng-template mlvTimelineItemMeta>
+      <mlv-badge color="success">Done</mlv-badge>
+    </ng-template>
+    Pull request merged to main.
+  </mlv-timeline-item>
+</mlv-timeline>
+```
+
+### Alternating left/right layout
+
+```html
+<mlv-timeline>
+  <mlv-timeline-item title="Step 1" timestamp="Jan 2025" tone="info" direction="right"> First step content on the right. </mlv-timeline-item>
+  <mlv-timeline-item title="Step 2" timestamp="Feb 2025" tone="success" direction="left"> Second step content on the left. </mlv-timeline-item>
+  <mlv-timeline-item title="Step 3" timestamp="Mar 2025" tone="warning" direction="right"> Third step content on the right. </mlv-timeline-item>
+</mlv-timeline>
+```
+
+### Dynamic timeline from data
+
+```typescript
+// component.ts
+interface TimelineEvent {
+  title: string;
+  timestamp: string;
+  description: string;
+  tone: MlvTimelineItemTone;
+}
+
+readonly events = signal<TimelineEvent[]>([
+  { title: 'Created', timestamp: '2025-01-10', description: 'Issue created.', tone: 'info' },
+  { title: 'In Progress', timestamp: '2025-01-12', description: 'Work started.', tone: 'warning' },
+  { title: 'Resolved', timestamp: '2025-01-15', description: 'Issue resolved.', tone: 'success' },
+]);
+```
+
+```html
+<mlv-timeline>
+  @for (event of events(); track event.timestamp) {
+  <mlv-timeline-item [title]="event.title" [timestamp]="event.timestamp" [tone]="event.tone"> {{ event.description }} </mlv-timeline-item>
+  }
+</mlv-timeline>
+```
+
+---
+
+## Dependencies
+
+### Angular / third-party
+
+| Package           | Usage                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@angular/core`   | `Component`, `Directive`, `input`, `contentChild`, `inject`, `TemplateRef`, `ViewEncapsulation`, `ChangeDetectionStrategy` |
+| `@angular/common` | `NgTemplateOutlet`                                                                                                         |
+
+### Internal (`@malva-ui/*`)
+
+| Package            | Usage                                                     |
+| ------------------ | --------------------------------------------------------- |
+| `@malva-ui/styles` | CSS custom properties (`--mlv-*` tokens), `mixins.base()` |

package/docs/ai/title.md

@@ -0,0 +1,105 @@
+# Library: title
+
+## Overview
+
+The Title library (`@malva-ui/core/title`) provides an inline heading-typography component that decorates the host element itself through the `[mlvTitle]` selector. It can infer heading size from native `h1` to `h6` tags, accept an explicit `level` override on any host element, render projected content or a bound value, and switch into an editable form-control mode backed by Angular's ControlValueAccessor API.
+
+## Public API
+
+Exported from `@malva-ui/core/title`:
+
+| Export          | Kind      | Description                                       |
+| --------------- | --------- | ------------------------------------------------- |
+| `MlvTitle`      | Component | Inline title component applied as `[mlvTitle]`    |
+| `MlvTitleLevel` | Type      | `1 \| 2 \| 3 \| 4 \| 5 \| 6` visual heading scale |
+
+---
+
+## Components
+
+### `MlvTitle`
+
+- **Selector:** `[mlvTitle]`
+- **Change Detection:** `OnPush`
+- 
+- 
+
+#### Inputs
+
+| Name          | Type                         | Default                | Description                                                     |
+| ------------- | ---------------------------- | ---------------------- | --------------------------------------------------------------- |
+| `level`       | `MlvTitleLevel \| undefined` | inferred from host tag | Visual heading size override                                    |
+| `editable`    | `boolean`                    | `false`                | Enables the synchronized `<pre>` + `<textarea>` editing surface |
+| `placeholder` | `string`                     | `''`                   | Placeholder text used by editable mode                          |
+| `readonly`    | `boolean`                    | `false`                | Prevents textarea editing when editable mode is active          |
+| `disabled`    | `boolean`                    | `false`                | Disables the control                                            |
+
+#### Model
+
+| Name    | Type                    | Default | Description                                                                  |
+| ------- | ----------------------- | ------- | ---------------------------------------------------------------------------- |
+| `value` | `Model<string \| null>` | `null`  | Signal-model API for the title text; takes precedence over projected content |
+
+#### Form Support
+
+- Implements `ControlValueAccessor`
+- Provides `NG_VALUE_ACCESSOR`
+- Provides `MLV_FORM_CONTROL`
+- Compatible with `[(ngModel)]`, `formControl`, and `formControlName`
+- Works inside `mlv-form-field`
+
+#### Rendering Rules
+
+- Native `h1` to `h6` hosts keep their semantics and infer `level` automatically
+- Non-heading hosts receive `role="heading"` and `aria-level`
+- Projected content is used when `value` is not bound
+- Editable mode hydrates its initial text from the projected content if needed
+- Bound `value` and form writes both feed the same internal editable state
+
+#### Styles Summary
+
+- Uses Malva UI heading typography tokens directly (`--mlv-typography-heading-h1-size` through `h6`)
+- Does not create component-scoped CSS variables for static token mappings
+- Editable mode overlays a transparent textarea on top of a synchronized `<pre>` so the heading auto-grows naturally
+
+---
+
+## Usage Examples
+
+```html
+<!-- Inferred from h1 -->
+<h1 mlvTitle>Quarterly roadmap</h1>
+
+<!-- Explicit level override -->
+<div mlvTitle level="2">Section heading</div>
+
+<!-- Signal-model binding -->
+<h2 mlvTitle editable [value]="headline()" (valueChange)="headline.set($event)"></h2>
+
+<!-- Template-driven forms -->
+<h3 mlvTitle editable name="title" [(ngModel)]="title"></h3>
+
+<!-- Reactive forms -->
+<h2 mlvTitle editable formControlName="title"></h2>
+```
+
+---
+
+## Accessibility Notes
+
+- Non-heading hosts get `role="heading"` and `aria-level`
+- Editable mode uses a native `<textarea>` for keyboard and assistive-technology compatibility
+- The visible heading typography remains the host element, preserving semantic structure when used on native heading tags
+
+## Dependencies
+
+- `@angular/forms`
+- `@angular/cdk`
+- `@malva-ui/core/form-utils`
+
+---
+
+## Field surface (2026-08)
+
+- The editable `<textarea>` now carries `[attr.aria-label]="ariaLabel()"` and `[attr.aria-required]="required() || null"` from the inherited base inputs.
+- `mlv-title` renders no `mlv-description` / `mlv-message` chrome, so the inherited `description` input has no effect and no `aria-describedby` is emitted — wrap the title in `mlv-form-field` when a field description is needed.