agnosticui-core 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/components/Timeline/react/ReactTimeline.tsx

@@ -1,34 +1,57 @@
-// v2/lib/src/components/Timeline/react/Timeline.tsx
-import React from "react";
-import { createComponent } from "@lit/react";
-import {
-  AgTimeline as AgTimelineWC,
-  AgTimelineItem as AgTimelineItemWC,
-} from "../core/Timeline.js";
-import type { AgTimelineProps, AgTimelineItemProps } from "../core/Timeline.js";
+// v2/lib/src/components/Timeline/react/ReactTimeline.tsx
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { AgTimeline as AgTimelineWC, AgTimelineItem as AgTimelineItemWC } from '../core/Timeline.js';
+
+// Extend React JSX IntrinsicElements to include custom timeline elements
+declare module 'react/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'ag-timeline-item': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+// Define the props for the Timeline component
+export interface ReactTimelineProps {
+  orientation?: 'horizontal' | 'vertical';
+  variant?: 'primary' | 'success' | 'warning' | 'danger' | 'monochrome' | '';
+  compact?: boolean;
+  ariaLabel?: string;
+  responsive?: boolean;
+  children?: React.ReactNode;
+}
 
 // Create React wrapper for Timeline
 export const ReactTimeline = createComponent({
-  tagName: "ag-timeline",
+  tagName: 'ag-timeline',
   elementClass: AgTimelineWC,
   react: React,
-  events: {
-    onSlotChange: "slotchange",
-  },
-});
-
-// Create React wrapper for TimelineItem
-export const ReactTimelineItem = createComponent({
-  tagName: "ag-timeline-item",
-  elementClass: AgTimelineItemWC,
-  react: React,
 });
 
-// Export types with better names for React context
-export type ReactTimelineProps = AgTimelineProps & {
+// Define the props for the TimelineItem component
+export interface ReactTimelineItemProps {
+  start?: React.ReactNode;
+  marker?: React.ReactNode;
+  end?: React.ReactNode;
   children?: React.ReactNode;
-};
+}
 
-export type ReactTimelineItemProps = AgTimelineItemProps & {
-  children?: React.ReactNode;
+// Custom TimelineItem to handle slots as props
+export const ReactTimelineItem: React.FC<ReactTimelineItemProps> = ({ start, marker, end, children }) => {
+  return (
+    <ag-timeline-item>
+      {start && <div slot="ag-start">{start}</div>}
+      {marker && <div slot="ag-marker">{marker}</div>}
+      {end && <div slot="ag-end">{end}</div>}
+      {children}
+    </ag-timeline-item>
+  );
 };
+
+// Original TimelineItem wrapper (if needed for other purposes)
+export const ReactTimelineItemWC = createComponent({
+  tagName: 'ag-timeline-item',
+  elementClass: AgTimelineItemWC,
+  react: React,
+});

package/src/components/Toggle/core/_Toggle.ts

@@ -34,6 +34,7 @@ import {
   type LabelPosition,
 } from '../../../shared/form-control-utils';
 import { formControlStyles } from '../../../shared/form-control-styles';
+import { FaceMixin, type ValidationMessages } from '../../../shared/face-mixin';
 
 // Event types
 export interface ToggleChangeEventDetail {
@@ -60,6 +61,7 @@ export interface ToggleProps {
   helpText?: string;
   name?: string;
   value?: string;
+  validationMessages?: ValidationMessages;
   // Event callbacks
   onClick?: (event: MouseEvent) => void;
   onToggleChange?: (event: ToggleChangeEvent) => void;
@@ -80,7 +82,7 @@ export interface ToggleProps {
  * - Size variants with consistent proportions
  * - Form integration support
  */
-export class AgToggle extends LitElement implements ToggleProps {
+export class AgToggle extends FaceMixin(LitElement) implements ToggleProps {
   static styles = [
     formControlStyles,
     css`
@@ -331,13 +333,7 @@ export class AgToggle extends LitElement implements ToggleProps {
   declare helpText: string;
 
   /**
-   * Form integration - name attribute
-   */
-  @property({ type: String })
-  declare name: string;
-
-  /**
-   * Form integration - value when checked
+   * Form integration - value submitted when checked (defaults to 'on' like native checkbox)
    */
   @property({ type: String })
   declare value: string;
@@ -348,6 +344,12 @@ export class AgToggle extends LitElement implements ToggleProps {
   @property({ attribute: false })
   declare onClick?: (event: MouseEvent) => void;
 
+  /**
+   * Consumer-supplied validation messages (overrides built-in English fallbacks)
+   */
+  @property({ attribute: false })
+  declare validationMessages: ValidationMessages | undefined;
+
   /**
    * Toggle change event callback
    */
@@ -377,11 +379,78 @@ export class AgToggle extends LitElement implements ToggleProps {
     this.invalid = false;
     this.errorMessage = '';
     this.helpText = '';
-    this.name = '';
     this.value = '';
+    this.validationMessages = undefined;
+  }
+
+  // ─── FACE ─────────────────────────────────────────────────────────────────
+
+  /**
+   * FACE lifecycle: called when the parent form is reset.
+   * Restores checked to false and clears form value and validity.
+   */
+  override formResetCallback(): void {
+    this.checked = false;
+    this._internals.setFormValue(null);
+    this._internals.setValidity({});
+    this._syncStates();
+  }
+
+  /**
+   * Sync validity state to ElementInternals.
+   * Toggle has no inner <input> to delegate to, so required validation
+   * is implemented directly: unchecked + required = valueMissing.
+   */
+  private _syncValidity(): void {
+    if (this.required && !this.checked) {
+      this._internals.setValidity(
+        { valueMissing: true },
+        this.validationMessages?.valueMissing ?? 'Please check this field.'
+      );
+    } else {
+      this._internals.setValidity({});
+    }
+  }
+
+  /**
+   * Sync CustomStateSet states so :state() pseudo-classes work from external CSS.
+   *
+   * Must be called AFTER _syncValidity() so that :state(invalid) reads the
+   * freshly-updated _internals.validity.valid value.
+   *
+   * Exposed states:
+   *  :state(checked)  — toggle is on
+   *  :state(disabled) — toggle is disabled
+   *  :state(readonly) — toggle is read-only
+   *  :state(required) — toggle is required
+   *  :state(invalid)  — FACE constraint validation is failing
+   */
+  private _syncStates(): void {
+    this._setState('checked', this.checked);
+    this._setState('disabled', this.disabled);
+    this._setState('readonly', this.readonly);
+    this._setState('required', this.required);
+    this._setState('invalid', !this._internals.validity.valid);
+  }
+
+  // ─── End FACE ─────────────────────────────────────────────────────────────
+
+  override updated(changedProperties: Map<string, unknown>) {
+    super.updated(changedProperties);
+    // FACE: sync states when disabled or readonly change programmatically.
+    // checked, required, and invalid are already handled via _performToggle
+    // and firstUpdated, but these two can change without going through toggle.
+    if (changedProperties.has('disabled') || changedProperties.has('readonly')) {
+      this._syncStates();
+    }
   }
 
   protected firstUpdated() {
+    // FACE: set initial form value and sync validity after first render
+    this._internals.setFormValue(this.checked ? (this.value || 'on') : null);
+    this._syncValidity();
+    this._syncStates();
+
     // Developer experience: warn about missing label
     if (!this.label && !this.noLabel) {
       // eslint-disable-next-line no-console
@@ -439,6 +508,11 @@ export class AgToggle extends LitElement implements ToggleProps {
 
     this.checked = !this.checked;
 
+    // FACE: sync form value and validity on every toggle
+    this._internals.setFormValue(this.checked ? (this.value || 'on') : null);
+    this._syncValidity();
+    this._syncStates();
+
     // Dispatch custom event with form integration details
     const toggleChangeEvent = new CustomEvent<ToggleChangeEventDetail>('toggle-change', {
       detail: {

package/src/components/Toggle/vue/VueToggle.vue

@@ -16,6 +16,7 @@
     :helpText="helpText"
     :name="name"
     :value="value"
+    .validationMessages="validationMessages"
     @click="handleClick"
     @toggle-change="handleToggleChange"
     v-bind="$attrs"
@@ -29,6 +30,7 @@ import type {
   ToggleChangeEvent,
   ToggleChangeEventDetail,
 } from "../core/Toggle";
+import type { ValidationMessages } from "../../../shared/face-mixin";
 import "../core/Toggle"; // Registers the ag-toggle web component
 
 // Define props interface (omit function props since wrapper uses emits)

package/src/shared/face-mixin.ts

@@ -0,0 +1,233 @@
+/**
+ * FaceMixin — Form Associated Custom Element (FACE) shared behaviors
+ *
+ * Adds the common FACE API surface to any LitElement subclass so that
+ * AgInput, AgCheckbox, AgSelect, AgRadio, etc. don't repeat this boilerplate.
+ *
+ * What every FACE component shares (lives here):
+ *  - `static formAssociated = true`
+ *  - `protected _internals` (ElementInternals handle)
+ *  - `name` property
+ *  - `get form/validity/validationMessage/willValidate`
+ *  - `checkValidity()` / `reportValidity()`
+ *  - `formDisabledCallback()` — syncs disabled from parent <fieldset disabled>
+ *  - No-op `formResetCallback()` — subclasses override for component-specific reset
+ *
+ * What stays in each component (NOT here):
+ *  - `formResetCallback()` implementation — each component knows its own default state
+ *  - `setFormValue()` calls — component decides when/what to submit
+ *  - `setValidity()` calls — component drives its own constraint validation
+ *
+ * Usage:
+ *   import { FaceMixin } from '../../../shared/face-mixin.js';
+ *   export class AgInput extends FaceMixin(LitElement) { ... }
+ */
+
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+
+// Standard Lit mixin type helper
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = {}> = new (...args: any[]) => T;
+
+/**
+ * Consumer-supplied validation messages for constraint validation.
+ * Each key maps to the corresponding ValidityState flag.
+ * Provided values override the built-in English fallback strings.
+ */
+export interface ValidationMessages {
+  valueMissing?: string;
+  typeMismatch?: string;
+  patternMismatch?: string;
+  tooLong?: string;
+  tooShort?: string;
+  rangeUnderflow?: string;
+  rangeOverflow?: string;
+  stepMismatch?: string;
+  badInput?: string;
+  customError?: string;
+}
+
+/**
+ * Sync the validity state of an inner <input> or <textarea> to ElementInternals.
+ *
+ * This is the recommended delegation strategy: let the native input run its own
+ * constraint validation (required, minlength, type="email", pattern, etc.) and
+ * then mirror the result into ElementInternals so the host custom element's
+ * validity reflects the inner element.
+ *
+ * Call this on every `input` and `change` event, and once after `firstUpdated`.
+ *
+ * @param internals - The ElementInternals handle from attachInternals()
+ * @param inputEl   - The inner native input, textarea, or select element
+ */
+export function syncInnerInputValidity(
+  internals: ElementInternals,
+  inputEl: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null | undefined
+): void {
+  if (!inputEl) return;
+
+  if (!inputEl.validity.valid) {
+    internals.setValidity(inputEl.validity, inputEl.validationMessage, inputEl);
+  } else {
+    internals.setValidity({});
+  }
+}
+
+/**
+ * Type-level declaration of everything FaceMixin adds to a class.
+ *
+ * Using `declare class` (rather than `interface`) is the Lit-recommended approach
+ * for mixins that include protected members — it avoids TS4094 "anonymous class
+ * type may not be private or protected" errors in declaration emit.
+ *
+ * Import this type when you need to declare a FACE-capable component in type position.
+ */
+export declare class FaceMixinInterface {
+  /** Registers this element as form-associated with the browser */
+  static readonly formAssociated: boolean;
+  /** ElementInternals handle — subclasses use this to call setFormValue/setValidity */
+  protected _internals: ElementInternals;
+  /** The name under which this control's value is submitted with the parent form */
+  name: string;
+  /** The parent <form> element, or null */
+  readonly form: HTMLFormElement | null;
+  /** Current ValidityState, updated via _internals.setValidity() */
+  readonly validity: ValidityState;
+  /** Browser-generated or custom validation message */
+  readonly validationMessage: string;
+  /** Whether this element participates in constraint validation */
+  readonly willValidate: boolean;
+  /** Silent validity check; fires 'invalid' event if invalid */
+  checkValidity(): boolean;
+  /** Validity check with browser tooltip if invalid */
+  reportValidity(): boolean;
+  /** FACE lifecycle — called when a fieldset disabled ancestor changes */
+  formDisabledCallback(disabled: boolean): void;
+  /** FACE lifecycle — called on form reset; subclasses should override */
+  formResetCallback(): void;
+  /**
+   * Toggle a custom state in ElementInternals.states (CustomStateSet).
+   * Enables :state() pseudo-class targeting from external CSS.
+   * Guards against environments where states is unavailable.
+   */
+  protected _setState(state: string, active: boolean): void;
+}
+
+/**
+ * FaceMixin
+ *
+ * Compose onto any LitElement subclass to get full FACE boilerplate.
+ * Subclasses MUST override `formResetCallback()` to restore their own default state.
+ */
+export const FaceMixin = <T extends Constructor<LitElement>>(superClass: T) => {
+  class FaceElement extends superClass {
+    /**
+     * Registers the element as form-associated with the browser.
+     * This is what enables ElementInternals and the form lifecycle callbacks.
+     */
+    static readonly formAssociated = true;
+
+    /**
+     * ElementInternals handle.
+     * Protected so subclasses can call setFormValue(), setValidity(), etc.
+     * Must be initialized in constructor before any other use.
+     */
+    protected _internals!: ElementInternals;
+
+    /**
+     * The name under which this control's value is submitted with the parent form.
+     * Mirrors the standard `name` attribute on native form controls.
+     * Reflected so it works in plain HTML: <ag-input name="email">
+     */
+    @property({ type: String, reflect: true })
+    name = '';
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(...args: any[]) {
+      super(...args);
+      // attachInternals() must be called in the constructor, before any other lifecycle
+      this._internals = this.attachInternals();
+    }
+
+    /** The parent <form> element, or null if not inside a form. */
+    get form(): HTMLFormElement | null {
+      return this._internals.form;
+    }
+
+    /** The current ValidityState, updated via this._internals.setValidity(). */
+    get validity(): ValidityState {
+      return this._internals.validity;
+    }
+
+    /** The browser-generated or custom validation message. */
+    get validationMessage(): string {
+      return this._internals.validationMessage;
+    }
+
+    /** Whether this element will participate in constraint validation. */
+    get willValidate(): boolean {
+      return this._internals.willValidate;
+    }
+
+    /** Checks validity silently; fires a cancellable 'invalid' event if invalid. */
+    checkValidity(): boolean {
+      return this._internals.checkValidity();
+    }
+
+    /** Checks validity and shows the browser validation tooltip if invalid. */
+    reportValidity(): boolean {
+      return this._internals.reportValidity();
+    }
+
+    /**
+     * FACE lifecycle: called when a <fieldset disabled> ancestor is toggled.
+     * Syncs the component's own `disabled` property so it renders correctly.
+     *
+     * Note: this only fires for inherited disabled state (via fieldset), not
+     * for the element's own `disabled` attribute — both paths must be handled.
+     */
+    formDisabledCallback(disabled: boolean): void {
+      // `disabled` is declared on each subclass via @property; cast to access it
+      (this as unknown as { disabled: boolean }).disabled = disabled;
+    }
+
+    /**
+     * FACE lifecycle: called when the parent form is reset.
+     * Default is a no-op. Subclasses MUST override to restore their default state
+     * and call this._internals.setFormValue('') / setValidity({}).
+     */
+    formResetCallback(): void {
+      // no-op default — override in subclass
+    }
+
+    /**
+     * Toggle a custom state in ElementInternals.states (CustomStateSet).
+     *
+     * Exposes internal states as CSS :state() pseudo-classes targetable from
+     * outside the shadow root — e.g. ag-toggle:state(checked), ag-radio:state(invalid).
+     *
+     * Always call this AFTER _syncValidity() so that :state(invalid) reads
+     * the freshly-updated _internals.validity.valid value.
+     *
+     * Feature-guarded: _internals.states requires Chrome 90+, Firefox 126+,
+     * Safari 17.4+. The guard is here so call sites don't repeat it.
+     *
+     * @param state  State name, e.g. 'checked', 'disabled', 'invalid'
+     * @param active True to add the state, false to remove it
+     */
+    protected _setState(state: string, active: boolean): void {
+      if (!this._internals.states) return;
+      if (active) {
+        this._internals.states.add(state);
+      } else {
+        this._internals.states.delete(state);
+      }
+    }
+  }
+
+  // Cast to FaceMixinInterface & T to avoid TS4094 errors in declaration emit
+  // caused by the anonymous class having protected members. The declare class above
+  // describes the same shape TypeScript-safely.
+  return FaceElement as unknown as Constructor<FaceMixinInterface> & T;
+};

package/src/shared/form-control-styles.ts

@@ -11,7 +11,7 @@ export const formControlStyles = css`
   /* Label - Default (top position) */
   .ag-form-control__label {
     display: block;
-    font-size: var(--ag-font-size-base);
+    font-size: var(--ag-font-size-sm);
     font-weight: 600;
     color: var(--ag-text-primary);
     line-height: var(--ag-line-height-base);

package/src/styles/ag-tokens-dark.css

@@ -96,6 +96,10 @@
   --ag-warning-text: #f2cc60;
   --ag-danger-background: #490202;
   --ag-danger-text: #ffc1ba;
+  --ag-primary-fg: #ffffff;
+  --ag-success-fg: #ffffff;
+  --ag-warning-fg: #0D1117;
+  --ag-danger-fg: #ffffff;
   --ag-border: #3D444D;
   --ag-border-subtle: #656C76;
   --ag-primary: #1158c7;

package/src/styles/ag-tokens.css

@@ -151,23 +151,27 @@
   --ag-background-primary-inverted: #1f2328;
   --ag-background-secondary: #f3f4f6;
   --ag-background-secondary-inverted: #111827;
-  --ag-background-tertiary: #e5e7eb;
-  --ag-background-disabled: #f3f4f6;
-  --ag-primary-background: #ddf4ff;
-  --ag-primary-text: #0550ae;
-  --ag-success-background: #dafbe1;
-  --ag-success-text: #116329;
-  --ag-info-background: #f3f4f6;
-  --ag-info-text: #4b5563;
-  --ag-warning-background: #fff8c5;
-  --ag-warning-text: #7d4e00;
-  --ag-danger-background: #ffebe9;
-  --ag-danger-text: #a40e26;
+  --ag-background-tertiary: #e5e7eb; /** Used by: Button default bg; also secondary button hover bg */
+  --ag-background-disabled: #f3f4f6; /** Used by: Button, Input, Checkbox, Radio, Select disabled states */
+  --ag-primary-background: #ddf4ff; /** Used by: Alert primary variant bg, Button faint variant bg */
+  --ag-primary-text: #0550ae; /** Used by: Alert primary text, Button bordered/outlined text + border */
+  --ag-success-background: #dafbe1; /** Used by: Alert success variant bg, Badge success variant bg */
+  --ag-success-text: #116329; /** Used by: Alert success variant text, Badge success variant text */
+  --ag-info-background: #f3f4f6; /** Used by: Alert info variant bg, Badge info variant bg */
+  --ag-info-text: #4b5563; /** Used by: Alert info variant text, Badge info variant text */
+  --ag-warning-background: #fff8c5; /** Used by: Alert warning variant bg, Badge warning variant bg */
+  --ag-warning-text: #7d4e00; /** Used by: Alert warning variant text, Badge warning variant text */
+  --ag-danger-background: #ffebe9; /** Used by: Alert danger variant bg, Badge danger variant bg */
+  --ag-danger-text: #a40e26; /** Used by: Alert danger variant text, Badge danger variant text */
+  --ag-primary-fg: #ffffff;
+  --ag-success-fg: #ffffff;
+  --ag-warning-fg: #111827;
+  --ag-danger-fg: #ffffff;
   --ag-border: #e5e7eb;
   --ag-border-subtle: #d1d5db;
   --ag-primary: #0550ae;
   --ag-primary-rgb: 5, 80, 174;
-  --ag-primary-border: #d1d5db;
+  --ag-primary-border: #d1d5db; /** Used by: Button bordered variant border */
   --ag-primary-dark: #0a3069;
   --ag-secondary: #6b7280;
   --ag-secondary-dark: #4b5563;
@@ -190,4 +194,5 @@
   --ag-rating-filled-success: #238636;
   --ag-rating-filled-warning: #9a6700;
   --ag-rating-filled-danger: #cf222e;
+  --ag-rating-filled-secondary: #6b7280;
 }