@cobwds/cob-button 1.19.4 → 1.23.1

package/dist/cob-button.d.ts

@@ -0,0 +1,338 @@
+import { CobFormControlElement } from "@cobwds/internals";
+import "@cobwds/cob-icon";
+/**
+ * A button for actions like saving, submitting, or navigating. Form-associated with full keyboard support.
+ *
+ * Use `filled` for primary actions (one per section), `outline` for secondary, `ghost` for tertiary,
+ * `text` for inline. Set `href` to render as a navigation link.
+ *
+ * ARIA belongs on the component's props, not on the `<cob-button>` host. The host has no role,
+ * so attributes placed there are not mapped into the accessibility tree and never reach the
+ * internal `<button>`. For a disclosure trigger use `ariaExpanded` together with `ariaControls`.
+ *
+ * @summary Button for actions and CTAs with variants, sizes, and icon support.
+ * @element cob-button
+ *
+ * @slot - Button label text. Use as fallback when `label` prop is not provided.
+ * @slot prefix-icon - Icon before label. Not shown for `text` variant.
+ * @slot suffix-icon - Icon after label. Not shown for `text` variant.
+ * @slot circle-icon - Icon for circle mode. Overrides `icon` prop.
+ *
+ * @cssprop [--cob-button-color] - Text color of the button label.
+ * @cssprop [--cob-button-color--hover] - Text color when hovered.
+ * @cssprop [--cob-button-color--active] - Text color when active/pressed.
+ * @cssprop [--cob-button-background-color] - Background color of the button.
+ * @cssprop [--cob-button-background-color--hover] - Background color when hovered.
+ * @cssprop [--cob-button-background-color--active] - Background color when active/pressed.
+ * @cssprop [--cob-button-border-color] - Border color of the button.
+ * @cssprop [--cob-button-border-color--hover] - Border color when hovered.
+ * @cssprop [--cob-button-border-color--active] - Border color when active/pressed.
+ *
+ * @fires {Event} cob-click - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.
+ * @fires {Event} cob-focus - Fired when the button receives focus.
+ * @fires {Event} cob-blur - Fired when the button loses focus.
+ *
+ * @usage
+ * - Use for the most important actions you want users to take, such as "Download", "Sign up", or "Log out".
+ * - Use `variant="fill"` for the primary action on the page. There should be only one primary action per page.
+ * - Use `variant="outline"` for secondary actions, placed next to the primary Fill button.
+ * - Use `variant="ghost"` buttons for additional actions beyond primary and secondary.
+ * - Use `variant="text"` buttons when an action needs to appear within a text block. If clicking takes the user somewhere else, use a Link instead.
+ * - Always set the `type` attribute (`submit`, `button`, or `reset`). The default is `button`.
+ * - Use sentence case for button labels, only capitalizing the first word.
+ * - Place a `chevron_down icon` on the right for buttons that open a dropdown.
+ * - Don't use buttons for navigation. Use an `<a>` element or Text button for links that take users somewhere else.
+ * - Don't use icons in buttons without a text label. Very few icons are universally understood.
+ * - Don't create custom button styles (color, shape, size). Consistency helps users recognize buttons and predict behavior.
+ *
+ * @example Basic
+ * ```html
+ * <cob-button label="Button" variant="filled"></cob-button>
+ * ```
+ *
+ * @example Variant Outline
+ * ```html
+ * <cob-button label="Button" variant="outline"></cob-button>
+ * ```
+ *
+ * @example Variant Ghost
+ * ```html
+ * <cob-button label="Button" variant="ghost"></cob-button>
+ * ```
+ *
+ * @example Variant Text
+ * ```html
+ * <cob-button label="Button" variant="text"></cob-button>
+ * ```
+ *
+ * @example Prefix Icon
+ * ```html
+ * <cob-button label="Previous" prefixIcon="chevron_left"></cob-button>
+ * ```
+ *
+ * @example Suffix Icon
+ * ```html
+ * <cob-button label="Next" suffixIcon="chevron_right"></cob-button>
+ * ```
+ *
+ * @example Slotted Icons
+ * ```html
+ * <cob-button label="Slotted icons">
+ *   <cob-icon color="#db117d" slot="prefix-icon" name="chevron_left"></cob-icon>
+ *   <cob-icon color="#db117d" slot="suffix-icon" name="chevron_right"></cob-icon>
+ * </cob-button>
+ * ```
+ *
+ * @example Circle icon button
+ * ```html
+ * <cob-button circle icon="close" label="Close dialog"></cob-button>
+ * ```
+ *
+ * @example Size Small
+ * ```html
+ * <cob-button label="Small" size="sm"></cob-button>
+ * ```
+ * @example Size Large
+ * ```html
+ * <cob-button label="Large" size="lg"></cob-button>
+ * ```
+ *
+ * @example Full width
+ * ```html
+ * <cob-button label="Full width" fullWidth></cob-button>
+ * ```
+ *
+ * @example Inverted
+ * ```html
+ * <cob-button label="Inverted" inverted></cob-button>
+ * ```
+ * @render Inverted
+ * ```html
+ * <div style="background: #1b1b1b; padding: 1rem;">
+ *   <cob-button label="Inverted" inverted></cob-button>
+ * </div>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <cob-button label="Disabled" disabled></cob-button>
+ * ```
+ *
+ * @example Href
+ * ```html
+ * <cob-button label="Visit Boston.gov" href="https://www.boston.gov/" target="_blank" suffixIcon="open_in_new"></cob-button>
+ * ```
+ *
+ * @example Type
+ * ```html
+ * <cob-button type="submit" label="Save Changes" variant="filled"></cob-button>
+ * ```
+ *
+ * @example Disclosure trigger
+ * ```html
+ * <cob-button
+ *   label="Here's how you know"
+ *   ariaExpanded="false"
+ *   ariaControls="trust-bar"
+ * ></cob-button>
+ * ```
+ */
+export declare class CobButton extends CobFormControlElement {
+    static styles: import("lit").CSSResult;
+    static shadowRootOptions: {
+        delegatesFocus: boolean;
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+    };
+    /**
+     * Unique identifier. Auto-generated if not provided.
+     */
+    id: string;
+    /**
+     * Name for form submission.
+     */
+    name: string;
+    /**
+     * Button height: `sm` (40px) for dense UIs, `md` (48px, default) for standard use, `lg` (56px) for prominent CTAs.
+     * @default "md"
+     */
+    size: "sm" | "md" | "lg";
+    /**
+     * Expands button to fill container width. Use for mobile layouts or stacked button groups.
+     * @default false
+     */
+    fullWidth: boolean;
+    /**
+     * Visual style: `filled` for primary (one per section), `outline` for secondary, `ghost` for tertiary, `text` for inline actions. Avoid `text` for navigation.
+     * @default "filled"
+     */
+    variant: "filled" | "outline" | "ghost" | "text";
+    /**
+     * Adjusts colors for dark backgrounds.
+     * @default false
+     */
+    inverted: boolean;
+    /**
+     * Visible button text. Use sentence case, action-oriented text (e.g., "Save Draft"). In `circle` mode it is visually hidden but still exposed to assistive tech as the accessible name.
+     */
+    label: string;
+    /**
+     * ID of controlled element (e.g., dropdown or modal). Sets `aria-controls`.
+     *
+     * Set this on `<cob-button>` rather than putting `aria-controls` on the host:
+     * the host has no role, so ARIA placed there is not mapped into the
+     * accessibility tree and never reaches the internal `<button>`.
+     */
+    ariaControls: string;
+    /**
+     * Disclosure state for buttons that show/hide content. Sets `aria-expanded`
+     * on the internal `<button>`/`<a>`.
+     *
+     * Use `"false"` when the controlled content is collapsed and `"true"` when it
+     * is expanded, updating it every time the content toggles. Leave unset for
+     * buttons that are not disclosure triggers — an `aria-expanded` that never
+     * changes is worse than none. Pair with `ariaControls` pointing at the
+     * element being shown or hidden.
+     *
+     * Setting `aria-expanded` directly on the `<cob-button>` host does nothing:
+     * a custom element with no role does not map its ARIA attributes into the
+     * accessibility tree, and host ARIA does not cross into the shadow root.
+     *
+     * @example
+     * ```html
+     * <cob-button
+     *   label="Here's how you know"
+     *   ariaExpanded="false"
+     *   ariaControls="trust-bar"
+     * ></cob-button>
+     * ```
+     */
+    ariaExpanded: "true" | "false" | "";
+    /**
+     * Marks this button as the current item within a set of related controls — the current
+     * page of a pagination control, the current step of a wizard. Sets `aria-current` on the
+     * internal `<button>`/`<a>`.
+     *
+     * Use `"page"` inside a pagination landmark, `"step"` inside a step indicator, and
+     * `"true"` when no more specific token fits. Only one control in a set is ever current:
+     * leave the property unset on all the others rather than setting `"false"`, which the
+     * spec reads as "explicitly not current" and adds nothing.
+     *
+     * Setting `aria-current` directly on the `<cob-button>` host does nothing: a custom
+     * element with no role does not map its ARIA attributes into the accessibility tree,
+     * and host ARIA does not cross into the shadow root.
+     *
+     * @example
+     * ```html
+     * <cob-button label="3" ariaCurrent="page"></cob-button>
+     * ```
+     */
+    ariaCurrent: "page" | "step" | "location" | "date" | "time" | "true" | "false" | "";
+    /**
+     * Material Symbol icon before label. Not shown for `circle` mode.
+     */
+    prefixIcon: string;
+    /**
+     * Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `circle` mode.
+     */
+    suffixIcon: string;
+    /**
+     * Renders circular icon-only button. Requires `icon` prop. `label` is rendered as visually-hidden text for the accessible name.
+     * @default false
+     */
+    circle: boolean;
+    /**
+     * Icon for circle mode. Required when `circle` is true. Scales with size (sm=24px, md=32px, lg=40px).
+     */
+    icon: string;
+    /**
+     * Prevents interaction. Avoid disabling without explanation—show validation errors instead.
+     * @default false
+     */
+    disabled: boolean;
+    /**
+     * Form `id` to associate with. Use when button is outside the form element.
+     */
+    form: string | null;
+    /**
+     * Value submitted with the form data, mirroring a native submit button.
+     *
+     * When `type="submit"` and both `name` and `value` are set, the entry
+     * `name=value` is included in the form's data only for submissions this
+     * button triggers. It is not included when the form is submitted another
+     * way (Enter in a text field, another button, `form.requestSubmit()`),
+     * and it is not readable from `new FormData(form)` outside a submission,
+     * matching native submitter semantics.
+     *
+     * A form-associated custom element cannot act as a native submitter, so
+     * the value is staged through `ElementInternals.setFormValue()` for the
+     * duration of the submission and cleared afterward.
+     */
+    value: string;
+    /**
+     * ID(s) of element(s) describing this button. Sets `aria-describedby`.
+     */
+    ariaDescribedBy: string;
+    /**
+     * Form behavior: `button` (default, no form action), `submit` (submits form), `reset` (resets form). Always set explicitly to avoid unintended submissions.
+     * @default "button"
+     */
+    type: "submit" | "reset" | "button";
+    /**
+     * Click handler. Use instead of `@click` to ensure keyboard accessibility.
+     *
+     * @deprecated Listen for the `cob-click` event instead. `cob-click`
+     * bubbles, is composed, and fires for both mouse and keyboard activation
+     * but never while disabled. This property still works but is excluded
+     * from generated framework wrappers and goes away in 2.0.
+     */
+    onClick: ((event: Event) => void) | null;
+    /**
+     * URL to navigate to. Renders as `<a>` tag. Omit for action buttons.
+     */
+    href: string;
+    /**
+     * Link target: `_self` (same tab), `_blank` (new tab—add `suffixIcon="open_in_new"`), `_parent`, `_top`, or frame name.
+     * @default "_self"
+     */
+    target: "_self" | "_blank" | "_parent" | "_top" | "framename";
+    private _hasPrefixSlot;
+    private _hasSuffixSlot;
+    private _hasCircleSlot;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     *
+     * Form association, ElementInternals, and id generation are provided by
+     * CobFormControlElement (@cobwds/internals). super.connectedCallback() assigns
+     * an id when one is not provided (prefix = the element's localName).
+     */
+    private _onPrefixSlotChange;
+    private _onSuffixSlotChange;
+    private _onCircleSlotChange;
+    private _manageFormAction;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
+    private _handleFocus;
+    private _handleBlur;
+    private _handleClick;
+    private _handleKeydown;
+    private _handleKeyup;
+    /**
+     * Handles inline onclick attributes for keyboard activation.
+     *
+     * Native clicks execute inline onclick attributes automatically, but
+     * keyboard activation of the custom element does not trigger that native
+     * behavior. Dispatching a synthetic click lets the browser's own inline
+     * event handler mechanism execute any onclick attribute safely without
+     * eval() or new Function().
+     */
+    private _handleAnyAttributeFunction;
+    focus(options?: FocusOptions): void;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/cob-button.figma.d.ts

@@ -0,0 +1 @@
+export {};