@rcarls/rc-field 0.0.0 → 0.7.0

package/dist/types/packages/rc-field/src/rc-field.d.ts

@@ -0,0 +1,187 @@
+import { LitElement, PropertyValues } from 'lit';
+declare global {
+    interface HTMLElementTagNameMap {
+        'rc-field': RCField;
+    }
+}
+export type RCFieldControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/**
+ * Accessible field wrapper for a native input, textarea, or select with labels and supporting
+ * text.
+ *
+ * The native control remains connected in light DOM and owns its value, form association,
+ * autofill, constraint validation, and native events. `rc-field` derives visual state from that
+ * control and wires a slotted label, hint, and error without replacing author-provided ARIA
+ * references. Programmatic native value writes are visible after calling `sync()`.
+ *
+ * Derived host attributes expose `data-focused`, `data-populated`, `data-disabled`,
+ * `data-readonly`, `data-required`, `data-invalid`, `data-multiline`, `data-has-label`, and
+ * `data-validation-attempted` for themes.
+ *
+ * A direct `<fieldset>` child groups several native controls into one field, such as an amount
+ * and its unit. Its `<legend>` names the group and shows as the field label, and each control
+ * keeps its own accessible name. The first text-like input or textarea is the primary control,
+ * and the others attach before or after it in source order. Supporting text describes the
+ * fieldset.
+ *
+ * @see {@link https://richardcarls.github.io/rc-webcomponents/components/rc-field rc-field docs}
+ * @see {@link https://m3.material.io/components/text-fields/overview Material Design 3 text fields}
+ *
+ * @slot - Required native `<input>`, `<textarea>`, or `<select>` control. An enhancing direct
+ *   child marked `data-rc-field-control` may own the native control as its direct child. A
+ *   `<fieldset>` with a `<legend>` instead groups several controls into one field.
+ * @slot label - Visible label; use a native `<label>` unless an ancestor label wraps the field
+ * @slot leading - Leading icon or control outside the editable content
+ * @slot trailing - Trailing icon or control outside the editable content
+ * @slot prefix - Text or content immediately before the native control
+ * @slot suffix - Text or content immediately after the native control
+ * @slot hint - Supporting guidance associated with the native control
+ * @slot error - Error text shown and associated after validation is attempted
+ *
+ * @attr counter - Shows the current native value length and `maxlength`, when present
+ * @attr invalid - Forces invalid presentation and supplies native `aria-invalid` when absent
+ * @attr [data-focused] - Present while the native control has focus
+ * @attr [data-populated] - Present while the native control has a value, or a single select's
+ *   selected option has visible label text
+ * @attr [data-disabled] - Mirrors the native control's disabled state
+ * @attr [data-readonly] - Mirrors the native control's readonly state
+ * @attr [data-required] - Mirrors the native control's required state
+ * @attr [data-invalid] - Present while an attempted or forced validation state is invalid
+ * @attr [data-multiline] - Present when the native control is a textarea
+ * @attr [data-has-label] - Present when the field has content in its label slot
+ * @attr [data-validation-attempted] - Present after the native control dispatches `invalid`
+ * @attr [data-control-provider] - Present when an enhancing direct child owns the native control
+ * @attr [data-group] - Present when a `<fieldset>` groups several controls into the field
+ *
+ * @cssprop [--rc-field-min-block-size=var(--rc-control-block-size, 2.5rem)] - Minimum field surface block size
+ * @cssprop [--rc-field-gap=var(--rc-control-gap, 0.5rem)] - Gap between leading, content, and trailing regions
+ * @cssprop [--rc-field-padding=var(--rc-control-padding-block, 0.5rem) var(--rc-control-padding-inline, 0.75rem)] - Field surface padding
+ * @cssprop [--rc-field-border=var(--rc-border, 1px solid ButtonBorder)] - Field surface border
+ * @cssprop [--rc-field-radius=var(--rc-control-radius, 0.125rem)] - Field surface corner radius
+ * @cssprop [--rc-field-background=var(--rc-field, Field)] - Field surface background
+ * @cssprop [--rc-field-color=var(--rc-field-text, FieldText)] - Input and affix text color
+ * @cssprop [--rc-field-label-color=var(--rc-field-text, CanvasText)] - Label color
+ * @cssprop [--rc-field-control-gap=var(--rc-control-gap, 0.25rem)] - Gap between control and prefix or suffix
+ * @cssprop [--rc-field-supporting-gap=var(--rc-control-gap, 0.5rem)] - Gap between supporting text and counter
+ * @cssprop [--rc-field-supporting-padding-block-start=0.25rem] - Supporting text top padding
+ * @cssprop [--rc-field-supporting-padding-inline=var(--rc-control-padding-inline, 0.75rem)] - Supporting text inline padding
+ * @cssprop [--rc-field-supporting-color=var(--rc-field-text, CanvasText)] - Hint and counter color
+ * @cssprop [--rc-field-supporting-font-size=0.75rem] - Hint, error, and counter font size
+ * @cssprop [--rc-field-error-color=Mark] - Invalid outline, label, and error color
+ * @cssprop [--rc-field-disabled-opacity=var(--rc-disabled-opacity, 0.6)] - Disabled field opacity
+ * @cssprop [--rc-field-focus-outline=var(--rc-focus-ring, 2px solid Highlight)] - Focus outline
+ * @cssprop [--rc-field-focus-outline-offset=var(--rc-focus-ring-offset, 0)] - Focus outline offset
+ *
+ * @csspart field - Field surface
+ * @csspart content - Label and editable content column
+ * @csspart label - Label container
+ * @csspart control - Native control, prefix, and suffix row
+ * @csspart leading - Leading content container
+ * @csspart trailing - Trailing content container
+ * @csspart prefix - Prefix content container
+ * @csspart suffix - Suffix content container
+ * @csspart supporting-text - Supporting text row
+ * @csspart hint - Hint container
+ * @csspart error - Error container
+ * @csspart counter - Character counter
+ */
+export declare class RCField extends LitElement {
+    static styles: import('lit').CSSResult[];
+    private static readonly _styledRoots;
+    private static _ensureBaseStyles;
+    /** Shows the current native value length and `maxlength`, when present. */
+    counter: boolean;
+    /** Forces invalid presentation and supplies native `aria-invalid` when absent. */
+    invalid: boolean;
+    private _hasControl;
+    private _hasLabel;
+    private _hasLeading;
+    private _hasTrailing;
+    private _hasPrefix;
+    private _hasSuffix;
+    private _hasHint;
+    private _hasError;
+    private _focused;
+    private _populated;
+    private _disabled;
+    private _readOnly;
+    private _required;
+    private _multiline;
+    private _grouped;
+    private _validationAttempted;
+    private _nativeInvalid;
+    private _validationMessage;
+    private _$controlRef;
+    private _$controlProviderRef;
+    private _$groupRef;
+    private _groupObserver;
+    private _$formRef;
+    private _controlObserver;
+    private _compositionObserver;
+    private _managedDescriptionIds;
+    private _managedIds;
+    private _managedLabel;
+    private _managedControlId;
+    private _managedAriaInvalid;
+    private readonly _controlController;
+    /**
+     * Returns the native control, or `null` when the field is incomplete. In a group, this is the
+     * primary control: the first text-like input or textarea, or else the first control.
+     */
+    get control(): RCFieldControl | null;
+    /** Returns the `<fieldset>` that groups the field's controls, or `null` for a single control. */
+    get group(): HTMLFieldSetElement | null;
+    /** Returns every native control the field manages, in source order. */
+    get controls(): RCFieldControl[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Focuses the native control. */
+    focus(options?: FocusOptions): void;
+    /** Removes focus from the native control. */
+    blur(): void;
+    /** Re-reads native value, validity, attributes, slots, and accessible relationships. */
+    sync(): void;
+    private _setupRoot;
+    private _setupGroup;
+    private _teardownGroup;
+    /** Re-resolves a group's primary control after its contents change. */
+    private _syncGroupControl;
+    private _setupControl;
+    private _teardownControl;
+    private _syncForm;
+    private _queueSync;
+    private readonly _onControlInput;
+    private readonly _onControlChange;
+    private readonly _onControlFocus;
+    private readonly _onControlBlur;
+    private readonly _onProviderFocusIn;
+    private readonly _onProviderFocusOut;
+    private readonly _onGroupFocusIn;
+    /** Moving focus between the group's own controls keeps the field focused. */
+    private readonly _onGroupFocusOut;
+    private readonly _onControlInvalid;
+    private readonly _onCompositionEnd;
+    private readonly _onFormReset;
+    private _syncState;
+    /**
+     * A control provider may disable its native control for a reason unrelated to the field's
+     * own enabled/disabled intent (`rc-select`'s picker guard force-disables a `multiple` native
+     * select to defeat a GeckoView label-activation bug, entirely independent of author intent).
+     * Prefer the provider's own `disabled` property, when it exposes one, over the raw control's
+     * — the same precedence `focus()`/`blur()` already give the provider over the control.
+     */
+    private _effectiveDisabled;
+    private _reflectStates;
+    private _effectiveInvalid;
+    private _syncSlots;
+    private _hasSlottedContent;
+    private _syncAssociations;
+    private _restoreAssociations;
+    private _ensureId;
+    private _warnGroupComposition;
+    private _warnComposition;
+    private _handleSurfaceClick;
+    private _slotClass;
+    protected render(): import('lit-html').TemplateResult<1>;
+}

package/dist/types/packages/rc-field/src/rc-field.styles.d.ts

@@ -0,0 +1,2 @@
+export declare const fieldStyles: import('lit').CSSResult;
+export default fieldStyles;

package/package.json

@@ -1,14 +1,65 @@
 {
   "name": "@rcarls/rc-field",
-  "version": "0.0.0",
-  "description": "Placeholder published only to register this package name on npm before configuring Trusted Publishing. Contains no code. Do not install or depend on this version.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.7.0",
+  "description": "Accessible field wrapper for a native input or textarea with labels and supporting text.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/richardcarls/rc-webcomponents.git"
+    "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
+    "directory": "packages/rc-field"
   },
+  "homepage": "https://richardcarls.github.io/rc-webcomponents/components/rc-field",
   "license": "MIT",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/rc-field.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/packages/rc-field/src/index.d.ts",
+        "default": "./dist/rc-field.js"
+      }
+    },
+    "./define": {
+      "import": {
+        "types": "./dist/types/packages/rc-field/src/define.d.ts",
+        "default": "./dist/rc-field-define.js"
+      }
+    }
+  },
+  "types": "./dist/types/packages/rc-field/src/index.d.ts",
+  "sideEffects": [
+    "./dist/rc-field-define.js"
+  ],
+  "customElements": "dist/custom-elements.json",
+  "scripts": {
+    "build": "tsc && vite build && cem analyze",
+    "cem:analyze": "cem analyze",
+    "preview": "vite preview",
+    "test:browser": "vitest --run",
+    "test:browser:chrome": "vitest --run --project=chromium",
+    "test:browser:firefox": "vitest --run --project=firefox"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@vitest/browser-playwright": "4.1.5",
+    "lit": "^3.0.0",
+    "playwright": "^1.56.0",
+    "rollup": "^4.60.2",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6",
+    "vitest-browser-lit": "^1.0.1"
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0"
+  },
+  "dependencies": {
+    "@rcarls/rc-common": "0.7.0"
   }
-}
+}