@scalable.software/pin 0.1.0

package/src/index.ts

@@ -0,0 +1,16 @@
+export { type Configuration } from "@scalable.software/component";
+
+export {
+  Tag,
+  Attributes,
+  State,
+  Visible,
+  Status,
+  Operation,
+  Event,
+  Gesture,
+} from "./pin.meta.js";
+
+export { Validate } from "./pin.validation.js";
+
+export { Pin } from "./pin.js";

package/src/pin.meta.ts

@@ -0,0 +1,108 @@
+/**
+ * @module Component
+ */
+
+export const Tag = "pin-button" as const;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ * @enum
+ */
+export const Attributes = {
+  VISIBLE: "visible",
+  STATUS: "status",
+} as const;
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ */
+export type Attributes = typeof Attributes;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ * @enum
+ */
+export const State = {
+  ...Attributes,
+} as const;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ */
+export type State = (typeof State)[keyof typeof State];
+
+/**
+ * Visible state used to show or hide the component
+ * @category Metadata: State
+ * @enum
+ */
+export const Visible = {
+  YES: "yes",
+  NO: "no",
+} as const;
+/**
+ * Visible state used to show or hide the component
+ * @category Metadata: State
+ */
+export type Visible = (typeof Visible)[keyof typeof Visible];
+
+/**
+ * @category Metadata: State
+ * @enum
+ */
+export const Status = {
+  PINNED: "pinned",
+  UNPINNED: "unpinned",
+} as const;
+/**
+ * @category Metadata: State
+ */
+export type Status = (typeof Status)[keyof typeof Status];
+
+/**
+ * @category Metadata: Operations
+ * @enum
+ */
+export const Operation = {
+  HIDE: "hide",
+  SHOW: "show",
+  PIN: "pin",
+  UNPIN: "unpin",
+  TOGGLE: "toggle",
+} as const;
+
+/**
+ * @category Metadata: Operations
+ */
+export type Operation = (typeof Operation)[keyof typeof Operation];
+
+/**
+ * @category Metadata: Events
+ * @enum
+ */
+export const Event = {
+  ON: "on",
+  ON_HIDE: "onhide",
+  ON_SHOW: "onshow",
+  ON_PIN: "onpin",
+  ON_UNPIN: "onunpin",
+} as const;
+/**
+ * @category Metadata: Events
+ */
+export type Event = (typeof Event)[keyof typeof Event];
+
+/**
+ * @category Metadata: Gesture
+ * @enum
+ */
+export const Gesture = {
+  CLICK: "click",
+} as const;
+/**
+ * @category Metadata: Gesture
+ */
+export type Gesture = (typeof Gesture)[keyof typeof Gesture];

package/src/pin.style.css

@@ -0,0 +1,133 @@
+/* =======================
+  Host Element Styles
+======================= */
+:host {
+  /* Light mode color variables */
+  --button-background-color: #ffffff;
+  --button-hover-background-color: #f3f3f3;
+  --button-active-background-color: #e1e1e1;
+  --button-border-color: #d1d1d1;
+  --button-border-hover-color: #a1a1a1;
+  --button-shadow-hover: 0 2px 6px rgba(0, 0, 0, 0.15);
+  --svg-fill-color: #5a5a5a;
+  --svg-hover-fill-color: #404040;
+  /* Shadow and radius */
+  --button-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);
+  --button-radius: 8px;
+  /* Sizes and margins */
+  --icon-size: 40px;
+  --icon-margin: 4px;
+  --svg-size: 24px;
+  --svg-margin: 8px;
+  display: inline-block;
+}
+/* Dark Mode Variables */
+@media (prefers-color-scheme: dark) {
+  :host {
+    /* Dark mode color variables */
+    --button-background-color: #1e1e1e;
+    --button-hover-background-color: #2a2a2a;
+    --button-active-background-color: #333333;
+    --button-border-color: #3c3c3c;
+    --button-border-hover-color: #4a4a4a;
+    --button-shadow: 0 1px 3px rgba(255, 255, 255, 0.12),
+      0 3px 8px rgba(0, 0, 0, 0.6);
+    --button-shadow-hover: 0 2px 6px rgba(255, 255, 255, 0.16),
+      0 6px 12px rgba(0, 0, 0, 0.6);
+    --svg-fill-color: #cfcfcf;
+    --svg-hover-fill-color: #ffffff;
+  }
+}
+
+/* =======================
+  Icon Styles
+======================= */
+.icon {
+  position: relative;
+  margin: var(--icon-margin);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--icon-size);
+  height: var(--icon-size);
+  background-color: var(--button-background-color);
+  border: 1px solid var(--button-border-color);
+  border-radius: var(--button-radius);
+  box-shadow: var(--button-shadow);
+  cursor: pointer;
+  transition: background-color 0.2s, border-color 0.2s, box-shadow 0.2s;
+}
+/* Active state styles for the icon (when clicked or tapped) */
+.icon:active {
+  background-color: var(--button-active-background-color);
+  border-color: var(--button-border-hover-color);
+  box-shadow: none;
+}
+
+/* =======================
+  Icon Hover Styles
+======================= */
+@media (hover: hover) {
+  .icon:hover {
+    background-color: var(--button-hover-background-color);
+    border-color: var(--button-border-hover-color);
+    box-shadow: var(--button-shadow-hover);
+  }
+}
+
+/* =======================
+  SVG Icon Styles
+======================= */
+svg {
+  margin: var(--svg-margin);
+  width: var(--svg-size);
+  height: var(--svg-size);
+  fill: var(--svg-fill-color);
+  transition: fill 0.2s, opacity 0.2s;
+}
+/* Hover effect for the SVG icons */
+@media (hover: hover) {
+  .icon:hover svg {
+    fill: var(--svg-hover-fill-color);
+  }
+}
+
+/* =======================
+  State Visibility
+======================= */
+:host([visible="no"]) {
+  display: none;
+}
+
+/* =======================
+  State Status
+======================= */
+.pinned {
+  display: none;
+}
+.unpinned {
+  display: inline-block;
+}
+
+/* =======================
+  State Status: Pinned
+======================= */
+:host([status="pinned"]) .icon {
+  background-color: var(--button-active-background-color);
+  border-color: var(--button-border-hover-color);
+}
+:host([status="pinned"]) .pinned {
+  display: inline-block;
+}
+:host([status="pinned"]) .unpinned {
+  display: none;
+}
+/* =======================
+  State Status: Unpinned
+======================= */
+:host([status="unpinned"]) .pinned {
+  display: none;
+}
+:host([status="unpinned"]) .unpinned {
+  display: inline-block;
+}

package/src/pin.template.html

@@ -0,0 +1,26 @@
+<template id="pin-button">
+  <div class="icon">
+    <svg
+      class="pinned"
+      height="24px"
+      width="24px"
+      viewBox="0 0 20 20"
+      fill="#212121"
+    >
+      <path
+        d="M2.85355 2.14645C2.65829 1.95118 2.34171 1.95118 2.14645 2.14645C1.95118 2.34171 1.95118 2.65829 2.14645 2.85355L6.896 7.60309L4.01834 8.75415C3.35177 9.02078 3.17498 9.88209 3.68262 10.3897L6.29289 13L3 16.2929V17H3.70711L7 13.7071L9.61027 16.3174C10.1179 16.825 10.9792 16.6482 11.2459 15.9817L12.3969 13.104L17.1464 17.8536C17.3417 18.0488 17.6583 18.0488 17.8536 17.8536C18.0488 17.6583 18.0488 17.3417 17.8536 17.1464L2.85355 2.14645ZM11.6276 12.3347L10.3174 15.6103L4.38973 9.68263L7.66531 8.3724L11.6276 12.3347ZM12.9565 10.7127C12.9294 10.7263 12.9026 10.7403 12.8761 10.7548L13.6202 11.4989L16.8622 9.87793C18.0832 9.26743 18.3473 7.64015 17.382 6.67486L13.3251 2.61804C12.3599 1.65275 10.7326 1.91683 10.1221 3.13783L8.5011 6.37977L9.24523 7.1239C9.25971 7.09739 9.27373 7.07059 9.28728 7.04349L11.0165 3.58504C11.3218 2.97454 12.1354 2.8425 12.618 3.32514L16.6749 7.38197C17.1575 7.86461 17.0255 8.67826 16.415 8.98351L12.9565 10.7127Z"
+      />
+    </svg>
+    <svg
+      class="unpinned"
+      height="24px"
+      width="24px"
+      viewBox="0 0 20 20"
+      fill="#212121"
+    >
+      <path
+        d="M10.1221 3.13782C10.7326 1.91683 12.3599 1.65275 13.3251 2.61804L17.382 6.67486C18.3472 7.64015 18.0832 9.26743 16.8622 9.87793L13.4037 11.6072C13.0751 11.7715 12.8183 12.0506 12.6818 12.3917L11.2459 15.9817C10.9792 16.6482 10.1179 16.825 9.61027 16.3174L7 13.7071L3.70711 17H3V16.2929L6.29289 13L3.68262 10.3897C3.17498 9.88209 3.35177 9.02078 4.01834 8.75415L7.60829 7.31817C7.94939 7.18173 8.22855 6.92486 8.39285 6.59628L10.1221 3.13782ZM12.618 3.32514C12.1354 2.8425 11.3217 2.97454 11.0165 3.58504L9.28727 7.04349C9.01345 7.59113 8.54818 8.01925 7.97968 8.24665L4.38973 9.68263L10.3174 15.6103L11.7534 12.0203C11.9808 11.4518 12.4089 10.9866 12.9565 10.7127L16.415 8.9835C17.0255 8.67826 17.1575 7.86461 16.6749 7.38197L12.618 3.32514Z"
+      />
+    </svg>
+  </div>
+</template>

package/src/pin.ts

@@ -0,0 +1,322 @@
+/**
+ * @module Component
+ */
+import { Component, Template } from "@scalable.software/component";
+import { type Configuration, type Handler } from "@scalable.software/component";
+
+import {
+  Tag,
+  Attributes,
+  Visible,
+  Status,
+  Event,
+  Gesture,
+} from "./pin.meta.js";
+
+import { Validate } from "./pin.validation.js";
+
+/**
+ * Configuration required for components with custom layout and style
+ * @category Configuration
+ */
+export const configuration: Configuration = {
+  url: import.meta.url,
+  template: {
+    id: Tag,
+  },
+  css: {
+    name: "pin.style.css",
+  },
+} as const;
+
+/**
+ * A pin button that can be:
+ * 1. pinned and unpinned
+ * 2. hidden and shown
+ * @category Components
+ */
+export class Pin extends Component {
+  /**
+   * The tag name of the component
+   * @category Configuration
+   */
+  public static get Tag() {
+    return Tag;
+  }
+
+  /**
+   * Only attributes defined the Attributes object will be observed in DOM
+   * @category Configuration
+   */
+  public static get Attributes(): Attributes {
+    return Attributes;
+  }
+
+  /**
+   * Helper function to load the component template into DOM
+   * @category Utility
+   */
+  public static Template = new Template(import.meta.url);
+
+  /**
+   * Cache element references to improve performance
+   * @category State
+   * @hidden
+   */
+  protected elements: { icon: HTMLDivElement | null } = { icon: null };
+
+  /**
+   * Internal Visibility state of the component
+   * @category State
+   * @default Visible.YES
+   * @hidden
+   */
+  private _visible: Visible = Visible.YES;
+
+  /**
+   * Internal Status state of the component
+   * @category State
+   * @default
+   * @hidden
+   */
+  private _status: Status = Status.UNPINNED;
+
+  /**
+   * on triggered when any event is triggered
+   * @category Events
+   * @hidden
+   */
+  private _on: Handler = null;
+
+  /**
+   * onhide triggered when pin visibility changes to hidden
+   * @category Events
+   * @hidden
+   */
+  private _onhide: Handler = null;
+
+  /**
+   * onshow triggered when pin visibility changes to visible
+   * @category Events
+   * @hidden
+   */
+  private _onshow: Handler = null;
+
+  /**
+   * onpin triggered when pin status changes to pinned
+   * @category Events
+   * @hidden
+   */
+  private _onpin: Handler = null;
+
+  /**
+   * onunpin triggered when pin state changes to unpinned
+   * @category Events
+   * @hidden
+   */
+  private _onunpin: Handler = null;
+
+  constructor() {
+    super(configuration);
+  }
+
+  /**
+   * Get and Sets the visibility of the pin button
+   * @category State
+   */
+  public get visible() {
+    return this.hasAttribute(Attributes.VISIBLE)
+      ? (this.getAttribute(Attributes.VISIBLE) as Visible)
+      : this._visible;
+  }
+  public set visible(visible: Visible) {
+    visible = visible ?? Visible.YES;
+
+    visible = Validate.visible(visible);
+
+    if (this._visible === visible) return;
+
+    this._visible = visible;
+
+    visible === Visible.YES && this.removeAttribute(Attributes.VISIBLE);
+    visible === Visible.NO && this.setAttribute(Attributes.VISIBLE, visible);
+
+    const event = { detail: { visible } };
+
+    visible === Visible.NO && this._dispatchEvent(Event.ON_HIDE, event);
+    visible === Visible.YES && this._dispatchEvent(Event.ON_SHOW, event);
+  }
+
+  /**
+   * Get and Sets the status of the pin button
+   * @category State
+   */
+  public get status(): Status {
+    return this.hasAttribute(Attributes.STATUS)
+      ? (this.getAttribute(Attributes.STATUS) as Status)
+      : this._status;
+  }
+  public set status(status: Status) {
+    status = Validate.status(status);
+
+    if (this._status === status) return;
+
+    this._status = status;
+
+    this.setAttribute(Attributes.STATUS, status);
+
+    const event = { detail: { status } };
+
+    status === Status.PINNED && this._dispatchEvent(Event.ON_PIN, event);
+    status === Status.UNPINNED && this._dispatchEvent(Event.ON_UNPIN, event);
+  }
+
+  /**
+   * Triggered on any event
+   * @event
+   * @category Events
+   */
+  public set on(handler: Handler) {
+    Object.values(Event)
+      .filter((event): event is Event => event !== Event.ON)
+      .forEach((event: Event) => {
+        this._on && this.removeEventListener(event, this._on);
+      });
+
+    this._on = handler;
+
+    Object.values(Event)
+      .filter((event): event is Event => event !== Event.ON)
+      .forEach((event: Event) => {
+        this._on && this.addEventListener(event, this._on);
+      });
+  }
+
+  /**
+   * Triggered via `.hide()`
+   * @event
+   * @category Events
+   */
+  public set onhide(handler: Handler) {
+    this._onhide && this.removeEventListener(Event.ON_HIDE, this._onhide);
+    this._onhide = handler;
+    this._onhide && this.addEventListener(Event.ON_HIDE, this._onhide);
+  }
+
+  /**
+   * Triggered via `.show()`
+   * @event
+   * @category Events
+   */
+  public set onshow(handler: Handler) {
+    this._onshow && this.removeEventListener(Event.ON_SHOW, this._onshow);
+    this._onshow = handler;
+    this._onshow && this.addEventListener(Event.ON_SHOW, this._onshow);
+  }
+
+  /**
+   * Triggered via `.pin()`
+   * @event
+   * @category Events
+   */
+  public set onpin(handler: Handler) {
+    this._onpin && this.removeEventListener(Event.ON_PIN, this._onpin);
+    this._onpin = handler;
+    this._onpin && this.addEventListener(Event.ON_PIN, this._onpin);
+  }
+
+  /**
+   * Triggered via `.unpin()`
+   * @event
+   * @category Events
+   */
+  public set onunpin(handler: Handler) {
+    this._onunpin && this.removeEventListener(Event.ON_UNPIN, this._onunpin);
+    this._onunpin = handler;
+    this._onunpin && this.addEventListener(Event.ON_UNPIN, this._onunpin);
+  }
+
+  /**
+   * Hide the pin button when it is visible
+   * @category Operations
+   */
+  public hide = () => (this.visible = Visible.NO);
+
+  /**
+   * Show the pin button when it is hidden
+   * @category Operations
+   */
+  public show = () => (this.visible = Visible.YES);
+
+  /**
+   * Pin the pin button when it is unpinned
+   * @category Operations
+   */
+  public pin = () => (this.status = Status.PINNED);
+
+  /**
+   * Unpin the pin button when it is pinned
+   * @category Operations
+   */
+  public unpin = () => (this.status = Status.UNPINNED);
+
+  /**
+   * Toggle the pin button between pinned and unpinned
+   * @category Operations
+   */
+  public toggle = () =>
+    (this.status =
+      this.status === Status.PINNED ? Status.UNPINNED : Status.PINNED);
+
+  /**
+   * List operations to perform for selected attributes being observed in the DOM.
+   * @category Configuration
+   * @hidden
+   */
+  protected _attributeHandlers = {
+    [Attributes.VISIBLE]: (value) => (this.visible = value),
+    [Attributes.STATUS]: (value) => (this.status = value),
+  };
+
+  /**
+   * Initialize component attributes with default values
+   * @category Configuration
+   * @hidden
+   */
+  protected _initialize = () => {
+    !this.hasAttribute(Attributes.STATUS) &&
+      this.setAttribute(Attributes.STATUS, this._status);
+  };
+
+  /**
+   * Cache element references to improve performance
+   * @category Configuration
+   * @hidden
+   */
+  protected _cache = () => {
+    this.elements.icon = this.root.querySelector(".icon");
+  };
+
+  /**
+   * Called by the connectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _addEventListeners = () =>
+    this.elements.icon.addEventListener(Gesture.CLICK, this._handleClick);
+
+  /**
+   * Called by the disconnectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _removeEventListeners = () =>
+    this.elements.icon.removeEventListener(Gesture.CLICK, this._handleClick);
+
+  /**
+   * Handles the click event
+   * @category Gesture
+   * @hidden
+   */
+  private _handleClick = (event: MouseEvent | TouchEvent) => this.toggle();
+}

package/src/pin.validation.ts

@@ -0,0 +1,29 @@
+import { Visible, Status } from "./pin.meta.js";
+
+export class Validate {
+  /**
+   * Validates that the value is a member of the `Visible` enum.
+   * Throws if the value is not a recognized visible state.
+   * @category Validation
+   */
+  public static visible = (value: string) => {
+    const valid = Object.values(Visible).includes(value as Visible);
+    if (!valid) {
+      throw new Error(`Invalid visible value: ${value}`);
+    }
+    return value as Visible;
+  };
+
+  /**
+   * Validates that the value is a member of the `Status` enum.
+   * Throws if the value is not a recognized status state.
+   * @category Validation
+   */
+  public static status = (value: string) => {
+    const valid = Object.values(Status).includes(value as Status);
+    if (!valid) {
+      throw new Error(`Invalid status value: ${value}`);
+    }
+    return value as Status;
+  };
+}