@skirbi/sugar 0.0.26 → 0.1.0

package/Changes

@@ -1,5 +1,28 @@
 Revision history for @skirbi/sugar
 
+0.1.0       2026-06-04 01:20:59Z
+
+  * BREAKING: Sugar components may no longer manually define
+    observedAttributes, attributeMap, or defaultConfig. Use attributeDefs
+    instead.
+
+    attributeDefs is now the only sugar attribute declaration API. The native
+    fields are derived by sugar so inheritance chains can work without static
+    generated state poisoning subclasses.
+
+    And because this is a rather big shift, we bump the minor. We had all the
+    letters of the alphabet ;)
+
+  * Add label position to (form)-inputs, this allows for a better DX I think.
+    It's small utility that allows the CSS to be predefined, easy recipe
+    handling without too much trouble. For those who want to override it, pick
+    `left`.
+
+  * Add error label position to (form)-inputs, this allows for a better DX I
+    think. It's small utility that allows the CSS to be predefined, easy recipe
+    handling without too much trouble. For those who want to override it, pick
+    `left`.
+
 0.0.26       2026-05-30 00:49:13Z
 
   * Introduce morphedCallbackSugar. Morphing is a delicate matter for

package/lib/htmlelement-input.mjs

@@ -24,42 +24,38 @@ export class HTMLElementSugarInput extends HTMLElementSugar {
   static controlSelector = '[wc-control]';
   static valueAttr = 'value';
 
-  // NOTE: this gets merged with subclass attributeDefs. If it doesn't, we
-  // still treat it as a reserved config key via deny-set collection.
-  static attributeDefs = {
-    'data-sync': { parser: parseBoolean, default: false },
-  };
-
-  // Collect attributeDefs keys across the inheritance chain
-  static _collectAttributeDefKeys(ctor) {
-    const keys = new Set();
-    let c = ctor;
-    while (c && c !== HTMLElementSugar) {
-      const defs = c.attributeDefs;
-      if (defs && typeof defs === 'object') {
-        for (const k of Object.keys(defs)) keys.add(k);
-      }
-      c = Object.getPrototypeOf(c);
-    }
-    return keys;
-  }
-
   /**
-   * Deny forwarding of:
-   * - all attributeDefs keys across the class chain
-   * - plus any keys present in getConfig() (extra safety if defs are not merged)
+   * Attributes owned by HTMLElementSugarInput itself.
+   *
+   * These are host-level behavior/layout flags. They are intentionally not part
+   * of `attributeDefs`, because subclasses define their own complete Sugar
+   * attribute contract and `attributeDefs` shadows through inheritance.
    */
-  getForwardDenySet() {
-    const keys = this.constructor._collectAttributeDefKeys(this.constructor);
+  static inputReservedAttributes = [
+    'data-sync',
+    'label-position',
+    'label-error-position',
+  ];
 
-    // If Sugar's getConfig includes parsed attrs, treat those as config too.
-    // This makes deny-set robust even if base attributeDefs aren't merged.
-    const cfg = this.getConfig?.();
-    if (cfg && typeof cfg === 'object') {
-      for (const k of Object.keys(cfg)) keys.add(k);
-    }
+  /**
+   * Valid label positions for controls that choose to use the shared helper.
+   * Components may override this, e.g. a pill toggle may add `inside`.
+   */
+  static labelPositions = ['top', 'right', 'bottom', 'left'];
+  static defaultLabelPosition = 'left';
+  static labelErrorPositions = ['top', 'right', 'bottom', 'left', 'inline'];
+  static defaultLabelErrorPosition = 'bottom';
 
-    return keys;
+  /**
+   * Deny forwarding of component config attributes and SugarInput-reserved host
+   * attributes. Do not walk the inheritance chain here: `attributeDefs` follows
+   * normal JavaScript static lookup/shadowing.
+   */
+  getForwardDenySet() {
+    return new Set([
+      ...Object.keys(this.constructor.attributeDefs ?? {}),
+      ...(this.constructor.inputReservedAttributes ?? []),
+    ]);
   }
 
   // Which attributes should never be forwarded by default
@@ -70,15 +66,71 @@ export class HTMLElementSugarInput extends HTMLElementSugar {
   // Whether we should mirror host attributes to the control after initial
   // render.
   shouldMirrorAttributes() {
-    const cfg = this.getConfig?.();
-    if (cfg && cfg['data-sync'] === true) return true;
-
-    // Fallback if attributeDefs inheritance/merge doesn't include data-sync:
     const raw = this.getAttribute('data-sync');
     if (raw === null) return false;
     return parseBoolean(raw);
   }
 
+  /**
+   * Resolve the effective label position for form-control components.
+   *
+   * This helper does not render anything by itself. Components that expose a
+   * label can call it and mirror the result to the host so Pinta can style the
+   * control layout with simple attribute selectors.
+   *
+   * @param {string} [defaultPosition]
+   * @returns {string}
+   */
+  getLabelPosition(defaultPosition = this.constructor.defaultLabelPosition || 'left') {
+    const raw = this.getAttribute('label-position') || defaultPosition;
+    const allowed = this.constructor.labelPositions ?? ['top', 'right', 'bottom', 'left'];
+
+    if (!allowed.includes(raw)) {
+      const tag = this.constructor.tag || this.constructor.name;
+      throw new Error(
+        `${tag}: invalid label-position "${raw}"; expected one of ${allowed.join(', ')}`
+      );
+    }
+
+    return raw;
+  }
+
+  /**
+   * Set the effective `label-position` on the host when it is omitted.
+   *
+   * @param {string} [defaultPosition]
+   * @returns {string}
+   */
+  syncLabelPosition(defaultPosition = this.constructor.defaultLabelPosition || 'left') {
+    const position = this.getLabelPosition(defaultPosition);
+    if (!this.hasAttribute('label-position')) {
+      this.setAttribute('label-position', position);
+    }
+    return position;
+  }
+
+  getLabelErrorPosition(defaultPosition = this.constructor.defaultLabelErrorPosition || 'bottom') {
+    const raw = this.getAttribute('label-error-position') || defaultPosition;
+    const allowed = this.constructor.labelErrorPositions ?? ['top', 'right', 'bottom', 'left', 'inline'];
+
+    if (!allowed.includes(raw)) {
+      const tag = this.constructor.tag || this.constructor.name;
+      throw new Error(
+        `${tag}: invalid label-error-position "${raw}"; expected one of ${allowed.join(', ')}`
+      );
+    }
+
+    return raw;
+  }
+
+  syncLabelErrorPosition(defaultPosition = this.constructor.defaultLabelErrorPosition || 'bottom') {
+    const position = this.getLabelErrorPosition(defaultPosition);
+    if (!this.hasAttribute('label-error-position')) {
+      this.setAttribute('label-error-position', position);
+    }
+    return position;
+  }
+
   // Find the control inside a rendered fragment.
   findControl(frag) {
     const sel = this.constructor.controlSelector || '[wc-control]';
@@ -180,6 +232,9 @@ export class HTMLElementSugarInput extends HTMLElementSugar {
     const deny = this.getForwardDenySet();
     const skip = this.getForwardSkipSet();
 
+    this.syncLabelPosition();
+    this.syncLabelErrorPosition();
+
     this.forwardAttrsTo(control, deny, skip);
     this.setupFormControl(control);
 

package/lib/htmlelement.mjs

@@ -6,16 +6,16 @@
  * Lightweight base class for authoring Web Components.
  *
  * Provides:
- * - Declarative attribute -> config mapping via static `attributeMap`
- * - Automatic attribute observation via `observedAttributes`
+ * - Declarative attribute -> config mapping via static `attributeDefs`
+ * - Automatic native attribute observation derived from `attributeDefs`
  * - Utility methods to register the element and define aliases
  *
  * @example
  * class MyComponent extends HTMLElementSugar {
  *   static tag = 'opndev-my-component';
- *   static observedAttributes = ['foo'];
- *   static attributeMap = { foo: parseBoolean };
- *   static defaultConfig = { foo: 'bar' };
+ *   static attributeDefs = {
+ *     foo: { default: 'bar', parser: parseBoolean },
+ *   };
  * }
  *
  * MyComponent.register();
@@ -25,6 +25,13 @@
 import { defined } from '@opndev/util/defined';
 import { registerDevAlias } from './aliases.mjs';
 
+const attributeMetaCache = new WeakMap();
+const sugarOwnedAttributeKeys = [
+  'observedAttributes',
+  'attributeMap',
+  'defaultConfig',
+];
+
 export class HTMLElementSugar extends HTMLElement {
 
   static renderGuardSelector = '';
@@ -40,20 +47,21 @@ export class HTMLElementSugar extends HTMLElement {
   }
 
   /**
-   * Sets up the element and transforms `attributeDefs` to
-   * `observedAttributes`, `attributeMap` and `defaultConfig`. Calling this
-   * multiple times on the component is ok, but discouraged.
+   * Sets up the element tag and template contract. Attribute metadata is
+   * derived lazily from `attributeDefs` and cached per constructor.
+   * Calling this multiple times on the same component is safe.
    */
   static init() {
+    if (Object.hasOwn(this, '_sugarInitialized')) return;
 
     this.checkTag();
-
-    if (!Object.hasOwn(this, '_sugarInitialized')) {
-      this.checkAttributes();
-      this._sugarInitialized = true;
-    }
-
+    this.checkAttributes();
     this.checkTemplate();
+
+    Object.defineProperty(this, '_sugarInitialized', {
+      value: true,
+      configurable: false,
+    });
   }
 
   static deriveTagFromClass() {
@@ -69,66 +77,132 @@ export class HTMLElementSugar extends HTMLElement {
     }
   }
 
+  /**
+   * Native attribute APIs are owned by Sugar. Component authors should define
+   * `attributeDefs`; Sugar derives `observedAttributes`, `attributeMap`, and
+   * `defaultConfig` from it.
+   */
   static checkAttributes() {
-    const hasDefs = !!this.attributeDefs;
-    const hasManualObserved = !!this.observedAttributes;
-    const hasManualMap = !!this.attributeMap;
-    const hasManualDefaults = !!this.defaultConfig;
-
-    if (!hasDefs) {
-      if (!hasManualObserved) this.observedAttributes = [];
-      if (!hasManualMap) this.attributeMap = {};
-      if (!hasManualDefaults) this.defaultConfig = {};
-      return;
+    for (const key of sugarOwnedAttributeKeys) {
+      const owner = this._findOwnStaticInChain(key);
+
+      if (owner && owner !== HTMLElementSugar) {
+        throw new Error(
+          `${this.name}: do not define static ${key}; use static attributeDefs`
+        );
+      }
     }
 
-    const hasManual = hasManualObserved || hasManualMap || hasManualDefaults;
+    this._sugarAttributeMeta();
+  }
+
+  /**
+   * Find the constructor in the inheritance chain that owns a static property.
+   *
+   * @param {string} key - Static property name to find.
+   * @returns {Function|null}
+   */
+  static _findOwnStaticInChain(key) {
+    let klass = this;
 
-    if (hasDefs && hasManual) {
-      throw new Error(
-        `${this.name}: Do not mix 'attributeDefs' with manual fields: ` +
-        `observedAttributes, attributeMap, defaultConfig`
-      );
+    while (klass && klass !== Function.prototype) {
+      if (Object.hasOwn(klass, key)) return klass;
+      klass = Object.getPrototypeOf(klass);
     }
 
-    const defs = this.attributeDefs;
+    return null;
+  }
 
-    this.observedAttributes = [];
-    this.attributeMap = {};
-    this.defaultConfig = {};
+  /**
+   * Native Custom Elements bridge. The browser reads this during
+   * `customElements.define()`.
+   *
+   * @returns {string[]}
+   */
+  static get observedAttributes() {
+    return this._sugarAttributeMeta().observedAttributes;
+  }
+
+  /**
+   * Attribute parser map derived from `attributeDefs`.
+   *
+   * @returns {Record<string, Function>}
+   */
+  static get attributeMap() {
+    return this._sugarAttributeMeta().attributeMap;
+  }
+
+  /**
+   * Default config derived from `attributeDefs`.
+   *
+   * @returns {Record<string, any>}
+   */
+  static get defaultConfig() {
+    return this._sugarAttributeMeta().defaultConfig;
+  }
+
+  /**
+   * Return compiled attribute metadata for this constructor.
+   * `attributeDefs` follows normal JavaScript static inheritance: inherited by
+   * lookup, shadowed by subclasses, and never merged by Sugar.
+   *
+   * @returns {{observedAttributes: string[], attributeMap: Record<string, Function>, defaultConfig: Record<string, any>}}
+   */
+  static _sugarAttributeMeta() {
+    if (attributeMetaCache.has(this)) {
+      return attributeMetaCache.get(this);
+    }
+
+    const meta = this._compileAttributeDefs(this.attributeDefs ?? {});
+    attributeMetaCache.set(this, meta);
+    return meta;
+  }
+
+  /**
+   * Compile `attributeDefs` into the native/Sugar attribute metadata.
+   *
+   * @param {Record<string, object|null|undefined>} defs
+   * @returns {{observedAttributes: string[], attributeMap: Record<string, Function>, defaultConfig: Record<string, any>}}
+   */
+  static _compileAttributeDefs(defs) {
+    if (Array.isArray(defs) || typeof defs !== 'object') {
+      throw new Error(`${this.name}: static attributeDefs must be an object`);
+    }
+
+    const observedAttributes = [];
+    const attributeMap = {};
+    const defaultConfig = {};
 
     for (const [key, spec] of Object.entries(defs)) {
       if (!defined(spec)) {
-        this.observedAttributes.push(key);
+        observedAttributes.push(key);
         continue;
       }
 
-      if (Array.isArray(spec)|| typeof spec !== 'object') {
+      if (Array.isArray(spec) || typeof spec !== 'object') {
         throw new Error(
           `${this.name}: 'attributeDefs' for key ${key} has an invalid spec`
         );
       }
 
-      if (!('observed' in spec) || spec.observed)
-        this.observedAttributes.push(key);
+      if (!('observed' in spec) || spec.observed) {
+        observedAttributes.push(key);
+      }
 
-      if ('default' in spec && defined(spec.default))
-        this.defaultConfig[key] = spec.default;
+      if ('default' in spec && defined(spec.default)) {
+        defaultConfig[key] = spec.default;
+      }
 
       if ('parser' in spec && defined(spec.parser)) {
-        if (typeof spec.parser !== 'function')
+        if (typeof spec.parser !== 'function') {
           throw new Error(`${this.name}: parser for ${key} must be a function`);
+        }
 
-        this.attributeMap[key] = spec.parser;
+        attributeMap[key] = spec.parser;
       }
-
     }
-    // This delete is intentional. We cannot keep it because it would otherwise
-    // break any subsequent init()/register() calls. For those coming from Perl
-    // this is a JS workaround for a Moose initarg. We essentially forbid both
-    // attributeDefs and formal HTMLElement
-    // observedAttributes/defaultConfig/attributeMap to coexist
-    delete this.attributeDefs;
+
+    return { observedAttributes, attributeMap, defaultConfig };
   }
 
   static checkTemplate() {

package/lib/index.mjs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: MIT
 
-const VERSION = "0.0.26";
+const VERSION = "0.1.0";
 
 export { HTMLElementSugar } from './htmlelement.mjs';
 export { HTMLElementSugarInput } from './htmlelement-input.mjs';

package/package.json

@@ -52,5 +52,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.0.26"
+  "version": "0.1.0"
 }