@scalable.software/pin 0.2.0

package/src/Index.ts

@@ -0,0 +1,25 @@
+export { type Configuration } from "@scalable.software/component";
+
+export {
+  Tag,
+  Attribute,
+  State,
+  Visible,
+  Status,
+  Operation,
+  Event,
+  Gesture,
+} from "./Pin.meta.js";
+
+export {
+  type Attributes,
+  type States,
+  type Visibility,
+  type Statuses,
+  type Operations,
+  type Events,
+  type Gestures,
+  type Handler,
+} from "./Pin.meta.js";
+
+export { Pin } from "./Pin.js";

package/src/Pin.meta.ts

@@ -0,0 +1,114 @@
+/**
+ * @module Component
+ */
+
+export const Tag = "pin-button" as const;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ * @enum
+ */
+export const Attribute = {
+  VISIBLE: "visible",
+  STATUS: "status",
+} as const;
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ */
+export type Attributes = typeof Attribute;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ * @enum
+ */
+export const State = {
+  ...Attribute,
+} as const;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata: State
+ */
+export type States = (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 Visibility = (typeof Visible)[keyof typeof Visible];
+
+/**
+ * @category Metadata: State
+ * @enum
+ */
+export const Status = {
+  PINNED: "pinned",
+  UNPINNED: "unpinned",
+} as const;
+/**
+ * @category Metadata: State
+ */
+export type Statuses = (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 Operations = (typeof Operation)[keyof typeof Operation];
+
+/**
+ * @category Metadata: Events
+ * @enum
+ */
+export const Event = {
+  ON_HIDE: "onhide",
+  ON_SHOW: "onshow",
+  ON_PIN: "onpin",
+  ON_UNPIN: "onunpin",
+  ON: "on",
+} as const;
+/**
+ * @category Metadata: Events
+ */
+export type Events = (typeof Event)[keyof typeof Event];
+
+/**
+ * @category Metadata: Gesture
+ * @enum
+ */
+export const Gesture = {
+  CLICK: "click",
+} as const;
+/**
+ * @category Metadata: Gesture
+ */
+export type Gestures = (typeof Gesture)[keyof typeof Gesture];
+
+/**
+ * Event handler signature
+ * @hidden
+ */
+export type Handler = (...args: any[]) => void;

package/src/Pin.style.css

@@ -0,0 +1,122 @@
+/* =======================
+  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;
+  --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;
+    --svg-fill-color: #cfcfcf;
+    --svg-hover-fill-color: #ffffff;
+    --button-shadow: 0 1px 4px rgba(0, 0, 0, 0.5);
+  }
+}
+/* =======================
+  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: 0 2px 6px rgba(0, 0, 0, 0.15);
+  }
+}
+/* =======================
+  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
+======================= */
+.pinned {
+  display: none;
+}
+.unpinned {
+  display: inline-block;
+}
+:host([visible="no"]) {
+  display: none;
+}
+
+/* =======================
+  State: 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: Unpinned
+======================= */
+:host([status="unpinned"]) .pinned {
+  display: none;
+}
+:host([status="unpinned"]) .unpinned {
+  display: inline-block;
+}

package/src/Pin.template.html

@@ -0,0 +1,12 @@
+<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,329 @@
+/**
+ * @module Component
+ */
+import { Component, Template } from "@scalable.software/component";
+import { type Configuration } from "@scalable.software/component";
+
+import { Tag, Attribute, Visible, Status, Event, Gesture } from "./Pin.meta.js";
+import {
+  type Attributes,
+  type Visibility,
+  type Statuses,
+  type Events,
+  type Handler,
+} from "./Pin.meta.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 Attribute;
+  }
+
+  /**
+   * Wait for the component to be defined before returning a collection of the component in the DOM
+   * @category Utilities
+   */
+  public static get = async () =>
+    (await customElements.whenDefined(Pin.Tag)) &&
+    (Array.from(document.querySelectorAll(Pin.Tag)) as Pin[]);
+
+  /**
+   * Helper function to load the component template into DOM
+   * @category Utilities
+   */
+  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: Visibility = Visible.YES;
+
+  /**
+   * Internal Status state of the component
+   * @category State
+   * @default
+   * @hidden
+   */
+  private _status: Statuses = 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(): Visibility {
+    return this.hasAttribute(Attribute.VISIBLE)
+      ? (this.getAttribute(Attribute.VISIBLE) as Visibility)
+      : this._visible;
+  }
+  public set visible(visible: Visibility) {
+    visible = visible || Visible.YES;
+    if (this._visible !== visible) {
+      this._visible = visible;
+      visible == Visible.YES && this.removeAttribute(Attribute.VISIBLE);
+      visible == Visible.NO && this.setAttribute(Attribute.VISIBLE, visible);
+
+      visible == Visible.NO &&
+        this._dispatchEvent(Event.ON_HIDE, { detail: { visible } });
+      visible == Visible.YES &&
+        this._dispatchEvent(Event.ON_SHOW, { detail: { visible } });
+    }
+  }
+
+  /**
+   * Get and Sets the status of the pin button
+   * @category State
+   */
+  public get status(): Statuses {
+    return this.hasAttribute(Attribute.STATUS)
+      ? (this.getAttribute(Attribute.STATUS) as Statuses)
+      : this._status;
+  }
+  public set status(status: Statuses) {
+    if (this._status !== status) {
+      this._status = status;
+      this.setAttribute(Attribute.STATUS, status);
+
+      status == Status.PINNED &&
+        this._dispatchEvent(Event.ON_PIN, { detail: { status } });
+      status == Status.UNPINNED &&
+        this._dispatchEvent(Event.ON_UNPIN, { detail: { status } });
+    }
+  }
+
+  /**
+   * Triggered on any event
+   * @event
+   * @category Events
+   */
+  public set on(handler: Handler) {
+    Object
+      .values(Event)
+      .filter((event): event is Events => event !== Event.ON)
+      .forEach((event: Events) => {
+        this._on && this.removeEventListener(event, this._on);
+        this._on = handler;
+        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 = {
+    [Attribute.VISIBLE]: (value) => (this.visible = value),
+    [Attribute.STATUS]: (value) => (this.status = value),
+  };
+
+  /**
+   * Initialize component attributes with default values
+   * @category Configuration
+   * @hidden
+   */
+  protected _initialize = () => this._initializeState();
+
+  /**
+   * Cache element references to improve performance
+   * @category Configuration
+   * @hidden
+   */
+  protected _cacheElements = () => this._cacheIcon();
+
+  /**
+   * 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);
+
+  /**
+   * Initialize component state with default values
+   * @category State
+   * @hidden
+   */
+  private _initializeState = () =>
+    this.setAttribute(Attribute.STATUS, this._status);
+
+  /**
+   * Cache icon element reference to improve performance
+   * @category State
+   * @hidden
+   */
+  private _cacheIcon = () =>
+    (this.elements.icon = this.root.querySelector(".icon"));
+
+  /**
+   * Handles the click event
+   * @category Gesture
+   * @hidden
+   */
+  private _handleClick = (event: MouseEvent | TouchEvent) => this.toggle();
+}