@govtechsg/sgds-web-component 0.0.7 → 0.0.10

package/src/utils/slot.ts

@@ -0,0 +1,102 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+
+export class HasSlotController implements ReactiveController {
+  host: ReactiveControllerHost & Element;
+  slotNames: string[] = [];
+
+  constructor(host: ReactiveControllerHost & Element, ...slotNames: string[]) {
+    (this.host = host).addController(this);
+    this.slotNames = slotNames;
+    this.handleSlotChange = this.handleSlotChange.bind(this);
+  }
+
+  private hasDefaultSlot() {
+    return [...this.host.childNodes].some(node => {
+      if (node.nodeType === node.TEXT_NODE && node.textContent!.trim() !== '') {
+        return true;
+      }
+
+      if (node.nodeType === node.ELEMENT_NODE) {
+        const el = node as HTMLElement;
+        const tagName = el.tagName.toLowerCase();
+
+        // Ignore visually hidden elements since they aren't rendered
+        if (tagName === 'sl-visually-hidden') {
+          return false;
+        }
+
+        // If it doesn't have a slot attribute, it's part of the default slot
+        if (!el.hasAttribute('slot')) {
+          return true;
+        }
+      }
+
+      return false;
+    });
+  }
+
+  private hasNamedSlot(name: string) {
+    return this.host.querySelector(`:scope > [slot="${name}"]`) !== null;
+  }
+
+  test(slotName: string) {
+    return slotName === '[default]' ? this.hasDefaultSlot() : this.hasNamedSlot(slotName);
+  }
+
+  hostConnected() {
+    this.host.shadowRoot!.addEventListener('slotchange', this.handleSlotChange);
+  }
+
+  hostDisconnected() {
+    this.host.shadowRoot!.removeEventListener('slotchange', this.handleSlotChange);
+  }
+
+  handleSlotChange(event: Event) {
+    const slot = event.target as HTMLSlotElement;
+
+    if ((this.slotNames.includes('[default]') && !slot.name) || (slot.name && this.slotNames.includes(slot.name))) {
+      this.host.requestUpdate();
+    }
+  }
+}
+
+/**
+ * Given a slot, this function iterates over all of its assigned element and text nodes and returns the concatenated
+ * HTML as a string. This is useful because we can't use slot.innerHTML as an alternative.
+ */
+export function getInnerHTML(slot: HTMLSlotElement): string {
+  const nodes = slot.assignedNodes({ flatten: true });
+  let html = '';
+
+  [...nodes].forEach(node => {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      html += (node as HTMLElement).outerHTML;
+    }
+
+    if (node.nodeType === Node.TEXT_NODE) {
+      html += node.textContent;
+    }
+  });
+
+  return html;
+}
+
+/**
+ * Given a slot, this function iterates over all of its assigned text nodes and returns the concatenated text as a
+ * string. This is useful because we can't use slot.textContent as an alternative.
+ */
+export function getTextContent(slot: HTMLSlotElement | undefined | null): string {
+  if (!slot) {
+    return '';
+  }
+  const nodes = slot.assignedNodes({ flatten: true });
+  let text = '';
+
+  [...nodes].forEach(node => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      text += node.textContent;
+    }
+  });
+
+  return text;
+}

package/src/utils/tabbable.ts

@@ -0,0 +1,81 @@
+/** Determines if the specified element is tabbable using heuristics inspired by https://github.com/focus-trap/tabbable */
+function isTabbable(el: HTMLElement) {
+  const tag = el.tagName.toLowerCase();
+
+  // Elements with a -1 tab index are not tabbable
+  if (el.getAttribute('tabindex') === '-1') {
+    return false;
+  }
+
+  // Elements with a disabled attribute are not tabbable
+  if (el.hasAttribute('disabled')) {
+    return false;
+  }
+
+  // Elements with aria-disabled are not tabbable
+  if (el.hasAttribute('aria-disabled') && el.getAttribute('aria-disabled') !== 'false') {
+    return false;
+  }
+
+  // Radios without a checked attribute are not tabbable
+  if (tag === 'input' && el.getAttribute('type') === 'radio' && !el.hasAttribute('checked')) {
+    return false;
+  }
+
+  // Elements that are hidden have no offsetParent and are not tabbable
+  if (el.offsetParent === null) {
+    return false;
+  }
+
+  // Elements without visibility are not tabbable
+  if (window.getComputedStyle(el).visibility === 'hidden') {
+    return false;
+  }
+
+  // Audio and video elements with the controls attribute are tabbable
+  if ((tag === 'audio' || tag === 'video') && el.hasAttribute('controls')) {
+    return true;
+  }
+
+  // Elements with a tabindex other than -1 are tabbable
+  if (el.hasAttribute('tabindex')) {
+    return true;
+  }
+
+  // Elements with a contenteditable attribute are tabbable
+  if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') {
+    return true;
+  }
+
+  // At this point, the following elements are considered tabbable
+  return ['button', 'input', 'select', 'textarea', 'a', 'audio', 'video', 'summary'].includes(tag);
+}
+
+/**
+ * Returns the first and last bounding elements that are tabbable. This is more performant than checking every single
+ * element because it short-circuits after finding the first and last ones.
+ */
+export function getTabbableBoundary(root: HTMLElement | ShadowRoot) {
+  const allElements: HTMLElement[] = [];
+
+  function walk(el: HTMLElement | ShadowRoot) {
+    if (el instanceof HTMLElement) {
+      allElements.push(el);
+
+      if (el.shadowRoot !== null && el.shadowRoot.mode === 'open') {
+        walk(el.shadowRoot);
+      }
+    }
+
+    [...el.children].forEach((e: HTMLElement) => walk(e));
+  }
+
+  // Collect all elements including the root
+  walk(root);
+
+  // Find the first and last tabbable elements
+  const start = allElements.find(el => isTabbable(el)) ?? null;
+  const end = allElements.reverse().find(el => isTabbable(el)) ?? null;
+
+  return { start, end };
+}

package/src/utils/watch.ts

@@ -0,0 +1,62 @@
+// @watch decorator
+//
+// Runs when an observed property changes, e.g. @property or @state, but before the component updates.
+//
+// To wait for an update to complete after a change occurs, use `await this.updateComplete` in the handler. To start
+// watching after the initial update/render, use `{ waitUntilFirstUpdate: true }` or `this.hasUpdated` in the handler.
+//
+// Usage:
+//
+//  @watch('propName')
+//  handlePropChange(oldValue, newValue) {
+//    ...
+//  }
+
+import type { LitElement } from "lit";
+
+type UpdateHandler = (prev?: unknown, next?: unknown) => void;
+
+type NonUndefined<A> = A extends undefined ? never : A;
+
+type UpdateHandlerFunctionKeys<T extends object> = {
+  [K in keyof T]-?: NonUndefined<T[K]> extends UpdateHandler ? K : never;
+}[keyof T];
+
+interface WatchOptions {
+  /**
+   * If true, will only start watching after the initial update/render
+   */
+  waitUntilFirstUpdate?: boolean;
+}
+
+export function watch(propName: string, options?: WatchOptions) {
+  const resolvedOptions: Required<WatchOptions> = {
+    waitUntilFirstUpdate: false,
+    ...options,
+  };
+  return <ElemClass extends LitElement>(
+    proto: ElemClass,
+    decoratedFnName: UpdateHandlerFunctionKeys<ElemClass>
+  ): void => {
+    // @ts-expect-error -- update is a protected property
+    const { update } = proto;
+    if (propName in proto) {
+      const propNameKey = propName as keyof ElemClass;
+      // @ts-expect-error -- update is a protected property
+      proto.update = function (this: ElemClass, changedProps: Map<keyof ElemClass, ElemClass[keyof ElemClass]>) {
+        if (changedProps.has(propNameKey)) {
+          const oldValue = changedProps.get(propNameKey);
+          const newValue = this[propNameKey];
+
+          if (oldValue !== newValue) {
+            if (!resolvedOptions.waitUntilFirstUpdate || this.hasUpdated) {
+              (this[decoratedFnName] as unknown as UpdateHandler)(oldValue, newValue);
+            }
+          }
+        }
+
+        update.call(this, changedProps);
+      };
+    }
+  };
+}

package/stories/ActionCard.stories.mdx

@@ -0,0 +1,199 @@
+import { Canvas, Meta, Story, ArgsTable } from "@storybook/addon-docs";
+import { html } from "lit-html";
+import "../lib/Card";
+
+<Meta
+  title='Components/Card/Action Card'
+  argTypes={{
+    bgColor: {
+      control: "select",
+      options: [
+        "primary",
+        "secondary",
+        "success",
+        "danger",
+        "warning",
+        "info",
+        "dark",
+        "light",
+      ],
+      defaultValue: "",
+      table: { category: "props" },
+      description: "Toggles the background color of the card",
+    },
+    textColor: {
+      control: "select",
+      options: [
+        "primary",
+        "secondary",
+        "success",
+        "danger",
+        "warning",
+        "info",
+        "dark",
+        "light",
+        "white",
+        "muted",
+      ],
+      defaultValue: "",
+      table: { category: "props" },
+      description: "Toggles the text color of the card",
+    },
+    borderColor: {
+      control: "select",
+      options: [
+        "primary",
+        "secondary",
+        "success",
+        "danger",
+        "warning",
+        "info",
+        "dark",
+        "light",
+      ],
+      defaultValue: "",
+      table: { category: "props" },
+      description: "Toggles the border color of the card",
+    },
+    active: {
+      control: "boolean",
+      description:
+        "By default, with variant card-action, set the active stylings when input is checked",
+      table: {
+        category: "props",
+        defaultValue: { summary: false },
+        type: {
+          summary: "boolean",
+        },
+      },
+    },
+    disabled: {
+      control: "boolean",
+      defaultValue: false,
+      table: { category: "props" },
+      description: "The disabled state of the card input",
+    },
+    iconName: {
+      control: "text",
+      defaultValue: "box",
+      table: {
+        category: "props",
+        type: { summary: "string" },
+      },
+      description:
+        "Optional. The name of the [bootstrap's icon](https://icons.getbootstrap.com/)",
+    },
+    cardSubtitleSlot: {
+      name: "card-subtitle",
+      control: "text",
+      defaultValue: "Laptop",
+      description: "Insert text here for card-subtitle slot",
+      table: {
+        category: "slots",
+        type: {
+          summary: "string",
+        },
+      },
+    },
+    cardTitleSlot: {
+      name: "card-title",
+      control: "text",
+      defaultValue: "Apple",
+      description: "Insert text here for card-title slot",
+      table: {
+        category: "slots",
+        type: {
+          summary: "string",
+        },
+      },
+    },
+    cardTextSlot: {
+      name: "card-text",
+      control: "text",
+      defaultValue: "Macbook Pro M1",
+      description: "Insert text here for card-text slot",
+      table: {
+        category: "slots",
+        type: {
+          summary: "string",
+        },
+      },
+    },
+    type: {
+      control: "select",
+      options: ["checkbox", "radio"],
+      defaultValue: "checkbox",
+      description:
+        "For variant card-action, change the type to radio or checkbox by default",
+      table: {
+        category: "props",
+        type: {
+          summary: "string",
+        },
+      },
+    },
+  }}
+/>
+
+export const Template = (args) =>
+  html`
+    <sgds-action-card
+      .active=${args.active}
+      .bgColor=${args.bgColor}
+      .borderColor=${args.borderColor}
+      .textColor=${args.textColor}
+      .disabled=${args.disabled}
+      .iconName=${args.iconName}
+      .type=${args.type}
+    >
+      <span slot="card-subtitle">${args.cardSubtitleSlot}</span>
+      <span slot="card-title">${args.cardTitleSlot}</span>
+      <span slot="card-text">${args.cardTextSlot}</span>
+    </sgds-action-card>
+  `;
+  export const TemplateType = (args) =>
+  html`
+  
+  <div class="col">
+    <sgds-action-card
+      type="radio"
+    >
+      <span slot="card-subtitle">${args.cardSubtitleSlot}</span>
+      <span slot="card-title">${args.cardTitleSlot}</span>
+      <span slot="card-text">${args.cardTextSlot}</span>
+    </sgds-action-card>
+  <div>
+  <div class="col">
+    <sgds-action-card
+      type="checkbox"
+    >
+      <span slot="card-subtitle">${args.cardSubtitleSlot}</span>
+      <span slot="card-title">${args.cardTitleSlot}</span>
+      <span slot="card-text">${args.cardTextSlot}</span>
+    </sgds-action-card>
+  <div>
+`;
+
+# SgdsActionCard
+
+Action Cards are Cards that are able to perform actions like selection or quantity toggling. Usually with built-in input elements.
+
+<Canvas>
+  <Story name='Basic'>{Template.bind({})}</Story>
+</Canvas>
+
+## API
+
+```jsx
+import { SgdsActionCard } from "@govtechsg/sgds-web-component";
+```
+
+<ArgsTable story='Basic' />
+
+## Type
+
+Use `type` prop : `radio` / `checkbox` to change the selectable card input type
+
+<Canvas>
+  <Story name='Type'>{TemplateType.bind({})}</Story>
+</Canvas>

package/stories/Button.stories.mdx

@@ -0,0 +1,194 @@
+import { Canvas, Meta, Story, ArgsTable } from "@storybook/addon-docs";
+import { html } from "lit-html";
+import "../lib/Button";
+
+<Meta
+  title="Components/Button"
+  argTypes={{
+    buttonClasses: { 
+      control: "text" ,
+      table: { category: "props" },
+      description: 'Optional. Can be used to insert any utility classes such as `me-auto`'
+    },
+    variant: {
+      control: 'select',
+      options: [
+        'primary',
+        'secondary',
+        'success',
+        'danger',
+        'warning',
+        'info',
+        'dark',
+        'light',
+        'link',
+        'icon',
+        'outline-primary',
+        'outline-secondary',
+        'outline-success',
+        'outline-danger',
+        'outline-warning',
+        'outline-info',
+        'outline-dark',
+        'outline-light',
+      ],
+      defaultValue: 'primary',
+      table: { category: "props" },
+      description: "One or more button variant combinations buttons may be one of a variety of visual variants such as: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `dark`, `light`, `link` as well as `outline` versions (prefixed by `outline-*`)"
+    },
+    size:{
+      control: 'select',
+      options:['(default)','sm','lg'],
+      description:'Specifies a large or small button',
+      table: { category: "props" },
+    },
+    active:{
+      control:'boolean',
+      defaultValue: false,
+      table: { category: "props" },
+      description: 'Manually set the visual state of the button to :active'
+    },
+    disabled:{
+      control: "boolean",
+      defaultValue: false,
+      table: { category: "props" },
+      description:'The disabled state of the button'
+    },
+    href:{
+      control:"text",
+      defaultValue: undefined,
+      table: { category: "props" },
+      description:'When set, the underlying button will be rendered as an `<a>` with this `href` instead of a `<button>`.'
+    },
+    target:{
+      control: 'select',
+      options:[
+        '_self',
+        '_blank',
+        '_parent',
+        '_top'
+      ],
+      defaultValue: '_self',
+      table: { category: "props" },
+      description:'Tells the browser where to open the link. Only used when `href` is set.'
+    },
+    download:{
+      control: 'text',
+      table: { category: "props" },
+      description: 'Tells the browser to download the linked file as this filename. Only used when `href` is set.'
+    },
+    form:{
+      control: 'text',
+      table: {
+         category: "props",
+         type: { summary: "string" },
+      },
+      description: 'The "form owner" to associate the button with. If omitted, the closest containing form will be used instead. The value of this attribute must be an id of a form in the same document or shadow root as the button. Read [more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-form)'
+    },
+    formAction:{
+      control: 'text',
+      table: {
+         category: "props",
+         type: { summary: "string" },
+      },
+      description: "Used to override the form owner's `action` attribute. Read [more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formaction)"
+    },
+    formMethod:{
+      control: 'select',
+      options:['_get','_post'],
+      table: {
+         category: "props",
+         type: { summary: "string" },
+      },
+      description: "Used to override the form owner's `method` attribute.. Read [more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formmethod)"
+    },
+    formNoValidate:{
+      control: 'boolean',
+      table: {
+         category: "props",
+         type: { summary: "boolean" },
+      },
+      description: "Used to override the form owner's `novalidate` attribute. Read [more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formnovalidate)"
+    },
+    formTarget:{
+      control: 'select',
+      options:[
+        '_self' , '_blank' , '_parent' , '_top'
+      ],
+      table: {
+         category: "props",
+         type: { summary: "string" },
+      },
+      description: "Used to override the form owner's `target` attribute. Read [more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formtarget)"
+    },
+    click:{
+      table: { 
+        category: "Method",
+        type: { summary: "Method" },
+      },
+      description: 'Simulates a click on the button.'
+    },
+    blur:{
+      table: { 
+        category: "Method",
+        type: { summary: "Method" },
+      },
+      description: 'Removes focus from the button.'
+    },
+    focus:{
+      table: { 
+        category: "Method",
+        type: { summary: "Method" },
+      },
+      description: 'Sets focus on the button.'
+    },
+    'sgds-blur':{
+      table: { 
+        category: "Events",
+        type: { summary: "Event" },
+      },
+      description: 'Removes focus from the button.'
+    },
+    'sgds-focus':{
+      table: { 
+        category: "Events",
+        type: { summary: "Event" },
+      },
+      description: 'Sets focus on the button.'
+    }
+  }}
+/>
+
+export const Template = (args) =>
+  html`
+    <sgds-button 
+      .variant=${args.variant} 
+      .buttonClasses=${args.buttonClasses} 
+      .size=${args.size}
+      .active=${args.active}
+      .disabled=${args.disabled}
+      .href=${args.href}
+      .target=${args.target}
+      .download=${args.download}
+    >
+      ${args.variant} 
+    </sgds-button>
+  `;
+
+# SgdsButton
+
+Buttons communicate actions that users can take throughout your portal which can be used in places such as modals, forms and cards
+
+<Canvas>
+  <Story name="Basic" args={{ variant: "primary" }}>
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+## API
+
+```jsx
+import { SgdsButton } from "@govtechsg/sgds-web-component";
+```
+
+<ArgsTable story="Basic" />