element: ak-checkbox

package.json

@@ -22,7 +22,7 @@
         "clean:artifacts": "rm -f tsconfig*.tsbuildinfo",
         "clean:dist": "rimraf ./dist",
         "fix:styles": "stylelint --fix 'src/**/*.css'",
-        "lint": "run-s -sn lint:types lint:eslint lint:package",
+        "lint": "run-s -n lint:types lint:eslint",
         "lint-staged": "lint-staged",
         "lint:eslint": "eslint --max-warnings 0 --fix",
         "lint:styles": "stylelint 'src/**/*.css'",

src/ak-checkbox/ak-checkbox.builder.ts

@@ -0,0 +1,91 @@
+import type { ElementRest } from "../types.js";
+import { CheckboxInput } from "./ak-checkbox.js";
+
+import { spread } from "@open-wc/lit-helpers";
+
+import { html, TemplateResult } from "lit";
+import { ifDefined } from "lit/directives/if-defined.js";
+
+/**
+ * Configuration options for the akCheckbox helper function
+ */
+export type CheckboxProps = ElementRest &
+    Partial<
+        Pick<
+            CheckboxInput,
+            | "name"
+            | "checked"
+            | "indeterminate"
+            | "required"
+            | "disabled"
+            | "value"
+            | "showLabel"
+            | "ariaLabel"
+        >
+    > & {
+        label?: TemplateResult | string;
+        labelOn?: TemplateResult | string;
+        icon?: TemplateResult | string;
+        indeterminateIcon?: TemplateResult | string;
+        reverse?: boolean;
+    };
+
+/**
+ * @summary Helper function to create a Checkbox component programmatically
+ *
+ * @returns {TemplateResult} A Lit template result containing the configured ak-checkbox element
+ *
+ * @see {@link CheckboxInput} - The underlying web component
+ */
+export function akCheckbox(options: CheckboxProps = {}): TemplateResult {
+    const {
+        name,
+        checked,
+        indeterminate,
+        required,
+        disabled,
+        value,
+        reverse,
+        showLabel,
+        ariaLabel,
+        label,
+        labelOn,
+        icon,
+        indeterminateIcon,
+        ...rest
+    } = options;
+
+    const intoSlot = (slot: string, s?: TemplateResult | string) =>
+        typeof s === "string" ? html`<span slot=${slot}>${s}</span>` : (s ?? "");
+
+    // The icon handling looks odd, but bear with it:
+    // - If icon is a string, we pass it as an attribute to checkbox,
+    //   so checkbox can look up the icon itself.
+    // - If icon is nullish, we put nothing into the template.
+    // - Otherwise, we assume icon is some renderable thing of
+    //   TemplateResultwith the proper `slot="icon"` attribute.
+    //
+    return html`
+        <ak-checkbox
+            ${spread(rest)}
+            name=${ifDefined(name)}
+            ?checked=${Boolean(checked)}
+            ?indeterminate=${Boolean(indeterminate)}
+            ?required=${Boolean(required)}
+            ?reverse=${Boolean(reverse)}
+            ?disabled=${Boolean(disabled)}
+            icon=${ifDefined(typeof icon === "string" ? icon : undefined)}
+            value=${ifDefined(value)}
+            ?label=${Boolean(showLabel)}
+            aria-label=${ifDefined(ariaLabel ?? undefined)}
+        >
+            ${intoSlot("label", label)}
+            <!-- -->
+            ${intoSlot("label-on", labelOn)}
+            <!-- -->
+            ${intoSlot("icon", icon)}
+            <!-- -->
+            ${intoSlot("indeterminate", indeterminateIcon)}
+        </ak-checkbox>
+    `;
+}

src/ak-checkbox/ak-checkbox.component.ts

@@ -0,0 +1,127 @@
+import "../ak-icon/ak-icon.js";
+
+import { AkLitElement } from "../component-base.js";
+import { FormAssociatedBooleanMixin } from "../mixins/form-associated-boolean-mixin.js";
+import styles from "./ak-checkbox.scss";
+
+import { match, P } from "ts-pattern";
+
+import { html, nothing } from "lit";
+import { property } from "lit/decorators.js";
+
+const CHECK_ICON = () =>
+    html`<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+        <path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z" />
+    </svg>`;
+
+const DOT_ICON = () => html`
+    <svg viewBox="0 0 16 16" fill="currentColor">
+        <path d="M4 8a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7A.5.5 0 0 1 4 8z" />
+    </svg>
+`;
+
+/**
+ * @element ak-checkbox
+ *
+ * @summary A checkbox component for boolean form inputs with customizable label positioning and accessibility features
+ *
+ * @attr {string} name - Name attribute for form submission
+ * @attr {boolean} checked - Whether the checkbox is checked
+ * @attr {boolean} required - Whether the checkbox is required in a form
+ * @attr {boolean} disabled - Whether the checkbox is disabled
+ * @attr {boolean} indeterminate - Whether the checkbox should show the "indeterminate" state
+ * @attr {string} value - Value submitted when checkbox is checked
+ * @attr {boolean} label - Whether to show label content alongside the checkbox
+ * @attr {boolean} reverse - Whether to reverse the checkbox and label positions
+ * @attr {string} aria-label - Aria label for the checkbox
+ *
+ * @fires change - Fired when the checkbox is toggled, contains detail with checked state and value
+ *
+ * @slot icon (Optional) - An alternative icon for the "checked" state
+ * @slot indeterminate (Optional) - An alternative icon for the "indeterminate" state
+ * @slot label (Optional) - Label content displayed next to the checkbox
+ * @slot label-on (Optional) - Label content displayed next to the checkbox when it is checked
+ *
+ * @csspart checkbox - The main container element
+ * @csspart toggle - The checkbox visual element
+ * @csspart label - The label container
+ *
+ * @cssprop --pf-v5-c-checkbox--FontSize - Font size of the checkbox component
+ * @cssprop --pf-v5-c-checkbox--LineHeight - Line height of the checkbox component
+ * @cssprop --pf-v5-c-checkbox--ColumnGap - Gap between checkbox and label
+ * @cssprop --pf-v5-c-checkbox__toggle--Height - Height of the checkbox
+ * @cssprop --pf-v5-c-checkbox__toggle--Width - Width of the checkbox
+ * @cssprop --pf-v5-c-checkbox__toggle--BorderColor - Border color of the checkbox
+ * @cssprop --pf-v5-c-checkbox__toggle--BorderRadius - Border radius of the checkbox
+ * @cssprop --pf-v5-c-checkbox__toggle--BorderWidth - Border width of the checkbox
+ * @cssprop --pf-v5-c-checkbox__toggle--Color - Color of the checkmark icon
+ * @cssprop --pf-v5-c-checkbox--focus__toggle--OutlineColor - Outline color when focused
+ * @cssprop --pf-v5-c-checkbox--focus__toggle--OutlineWidth - Outline width when focused
+ * @cssprop --pf-v5-c-checkbox--disabled__toggle--Color - Color when disabled
+ * @cssprop --pf-v5-c-checkbox--disabled__label--Color - Label color when disabled
+ * @cssprop --pf-v5-c-checkbox__label--Color - Default label color
+ */
+export class CheckboxInput extends FormAssociatedBooleanMixin(AkLitElement) {
+    static readonly styles = [styles];
+
+    @property({ type: Boolean, attribute: "show-label" })
+    public showLabel = false;
+
+    @property({ type: Boolean })
+    public indeterminate = false;
+
+    connectedCallback() {
+        super.connectedCallback();
+        if (!this.hasAttribute("role")) {
+            this.setAttribute("role", "checkbox");
+        }
+    }
+
+    protected renderIcon() {
+        const [hasIndeterminate, hasIcon] = [
+            this.hasSlotted("indeterminate"),
+            this.hasSlotted("icon"),
+        ];
+        return match([this.indeterminate, this.checked, hasIndeterminate, hasIcon])
+            .with([false, false, P._, P._], () => nothing)
+            .with([true, P._, false, P._], () => DOT_ICON())
+            .with([true, P._, true, P._], () => html`<slot name="indeterminate"></slot>`)
+            .with([false, true, P._, false], () => CHECK_ICON())
+            .with([false, true, P._, true], () => html`<slot name="icon"></slot>`)
+            .exhaustive();
+    }
+
+    protected renderLabel() {
+        return this.hasSlotted("label-on") && this.checked
+            ? html`<slot name="label-on"></slot>`
+            : html`<slot name="label"></slot>`;
+    }
+
+    private renderCheckbox() {
+        return html`<div part="toggle">${this.renderIcon()}</div>`;
+    }
+
+    private renderWithLabels() {
+        return html`<div part="toggle">${this.renderIcon()}</div>
+            <span part="label"> ${this.renderLabel()} </span>`;
+    }
+
+    public override render() {
+        return html`
+            <div part="checkbox">
+                ${this.hasSlotted("label") ? this.renderWithLabels() : this.renderCheckbox()}
+            </div>
+        `;
+    }
+
+    public override setAriaChecked() {
+        this.setAriaAttribute(
+            "aria-checked",
+            match([this.indeterminate, this.checked])
+                .with([true, P._], () => "mixed")
+                .with([false, true], () => "true")
+                .with([false, false], () => "false")
+                .exhaustive(),
+        );
+    }
+}

src/ak-checkbox/ak-checkbox.css

@@ -0,0 +1,135 @@
+/* Checkbox is a wholly custom component, so there's no WCCSS file. */
+
+:host {
+    --checkbox--FontSize: var(--pf-v5-c-checkbox--FontSize, 1rem);
+    --checkbox__label--PaddingLeft: var(--pf-v5-c-checkbox__label--PaddingLeft, 1rem);
+    --checkbox--ColumnGap: var(--checkbox__label--PaddingLeft);
+    --checkbox--LineHeight: var(--pf-v5-c-checkbox--LineHeight, 1.5);
+    --checkbox--Height: calc(var(--checkbox--FontSize) * var(--checkbox--LineHeight));
+    --checkbox--Width: auto;
+    --checkbox__toggle--Color: var(--pf-v5-c-checkbox__toggle--Color, #151515);
+    --checkbox__toggle--BorderRadius: var(--pf-v5-c-checkbox__toggle--BorderRadius, 3px);
+    --checkbox__toggle--BorderColor: var(--checkbox__toggle--Color);
+    --checkbox__toggle--BorderWidth: var(--pf-v5-c-checkbox__toggle--BorderWidth, 2px);
+    --checkbox__toggle--Height: var(--checkbox--FontSize);
+    --checkbox__toggle--Width: var(--checkbox__toggle--Height);
+    --checkbox__toggle--BackgroundColor: inherit;
+    --checkbox__toggle--Padding: 1px;
+    --checkbox--disabled__toggle--Color: var(--pf-v5-c-checkbox--disabled__toggle--Color, #6a6e73);
+    --checkbox--disabled__toggle--BorderColor: var(
+        --pf-v5-c-checkbox--disabled__toggle--BorderColor,
+        #d2d2d2
+    );
+    --checkbox--disabled__toggle--BackgroundColor: var(
+        --pf-v5-c-checkbox--disabled__toggle--BackgroundColor,
+        #f5f5f5
+    );
+    --checkbox--disabled__label--Color: var(--pf-v5-c-checkbox--disabled__label--Color, #6a6e73);
+    --checkbox--focus__toggle--OutlineWidth: var(
+        --pf-v5-c-checkbox--focus__toggle--OutlineWidth,
+        2px
+    );
+    --checkbox--focus__toggle--OutlineOffset: var(
+        --pf-v5-c-checkbox--focus__toggle--OutlineOffset,
+        0.5rem
+    );
+    --checkbox--focus__toggle--OutlineColor: var(
+        --pf-v5-c-checkbox--focus__toggle--OutlineColor,
+        #06c
+    );
+    --checkbox__input--checked__label--Color: var(--pf-v5-c-checkbox__toggle--Color);
+    --checkbox__input--not-checked__label--Color: var(
+        --pf-v5-c-checkbox__input--not-checked__label--Color,
+        #6a6e73
+    );
+    --checkbox__label--Color: var(--pf-v5-c-checkbox__label--Color, #151515);
+
+    position: relative;
+    display: inline;
+}
+
+[part="checkbox"] {
+    position: relative;
+    grid-template-columns: auto;
+    grid-auto-columns: 1fr;
+    column-gap: var(--checkbox--ColumnGap);
+    height: var(--checkbox--Height);
+    font-size: var(--checkbox--FontSize);
+    line-height: var(--checkbox--LineHeight);
+    vertical-align: middle;
+    cursor: pointer;
+    display: grid;
+}
+
+:host([reverse]) [part="label"] {
+    grid-row: 1;
+    grid-column: 1;
+}
+
+:host([reverse]) [part="toggle"] {
+    grid-column: 2;
+}
+
+:host([checked]) [part="label"] {
+    color: var(--checkbox__input--checked__label--Color);
+}
+
+[part="checkbox"]:focus-visible [part="toggle"] {
+    outline: var(--checkbox--focus__toggle--OutlineWidth) solid
+        var(--checkbox--focus__toggle--OutlineColor);
+    outline-offset: var(--checkbox--focus__toggle--OutlineOffset);
+}
+
+[part="toggle"] {
+    display: flex;
+    display: inline-flex;
+    justify-content: center; /* Centers horizontally */
+    align-items: center; /* Centers vertically */
+    width: var(--checkbox__toggle--Width);
+    height: var(--checkbox__toggle--Height);
+    border-style: solid;
+    border-radius: var(--checkbox__toggle--BorderRadius);
+    border-color: var(--checkbox__toggle--BorderColor);
+    border-width: var(--checkbox__toggle--BorderWidth);
+}
+
+[part="toggle"] > svg {
+    width: calc(var(--checkbox__toggle--Width) - 2 * var(--checkbox__toggle--Padding));
+    height: calc(var(--checkbox__toggle--Height) - 2 * var(--checkbox__toggle--Padding));
+    fill: var(--checkbox__toggle--Color);
+}
+
+[part="toggle"] > svg > path {
+    fill: var(--checkbox__toggle--Color);
+}
+
+:host(:disabled),
+:host([disabled]) {
+    cursor: not-allowed;
+}
+
+:host(:disabled) [part="label"],
+:host([disabled]) [part="label"] {
+    color: var(--checkbox--disabled__label--Color);
+    cursor: not-allowed;
+}
+
+:host(:disabled) [part="toggle"],
+:host([disabled]) [part="toggle"] {
+    --checkbox__toggle--BorderColor: var(--checkbox--disabled__toggle--BorderColor);
+
+    cursor: not-allowed;
+    background-color: var(--checkbox--disabled__toggle--BackgroundColor);
+}
+
+:host(:disabled) [part="toggle"],
+:host([disabled]) [part="toggle"] {
+    --checkbox__toggle--Color: var(--checkbox--disabled__toggle--Color);
+}
+
+[part="label"] {
+    display: inline-block;
+    grid-column: 2;
+    color: var(--checkbox__label--Color);
+    vertical-align: top;
+}