face-up 0.0.0 → 0.0.2

package/types/assign-gingerly/types.d.ts

@@ -0,0 +1,328 @@
+export type EnhKey = string | symbol;
+
+// type NoUnderscore<T extends string> = T extends `_${string}` ? never : T;
+
+// type YesUnderscore = `_${string}`;
+
+// export type StringWithAutocompleteOptions<TOptions> = 
+//     | (string & {})
+//     | TOptions;
+
+// export type StringNotStartWithUnderscoreAutocompleteOptions<TOptions> = 
+//     | (NoUnderscore<string> & {})
+//     | TOptions;
+
+// export type StringStartWithUnderscoreAutocompleteOptions<TOptions> = 
+//     | (YesUnderscore & {})
+//     | TOptions;
+
+//used by mount-observer, not by assign-gingerly
+type DisposeEvent = 
+    | 'disconnect' 
+    | 'dismount'
+    // cannot polyfill
+    | 'exit' // element moved outside customElementRegistry
+    //reference count outside any enhancements goes to zero
+    | 'dispose'
+
+export type Spawner<T = any, Obj = Element> = {
+  new (obj?: Obj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+  canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
+}
+
+export interface EnhancementConfigBase<T = any> {
+    //Allow unprefixed attributes for custom elements and SVG when element tag name matches pattern
+    allowUnprefixed?: string | RegExp;
+    
+    //keys of type symbol are used for dependency injection
+    //and are used by assign-gingerly
+    symlinks?: { [key: symbol]: keyof T };
+    
+    lifecycleKeys?: 
+    | true  // Use standard names: "dispose" method, "resolved" property/event
+    | {
+        dispose?: string | symbol,
+        resolved?: string | symbol
+      }
+    //used by mount-observer, not by assign-gingerly
+    //impossible to polyfill, but will always be disposed
+    //when oElement's reference count goes to zero
+    disposeOn?: DisposeEvent | DisposeEvent[]
+}
+
+/**
+ * Configuration for enhancing elements with class instances
+ * Defines how to spawn and initialize enhancement classes
+ */
+export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementConfigBase<T> {
+  
+  spawn: Spawner<T, Obj>;
+  
+  //Applicable to passing in the initVals during the spawn lifecycle event
+  withAttrs?: AttrPatterns<T>;
+  
+
+  //only applicable when spawning from a DOM Element reference
+  enhKey?: EnhKey;
+    
+}
+
+export type Constructor = new (...args: any[]) => any;
+
+export type pathString = `?.${string}`;
+
+export type CustomElementName = string;
+export type CustomElementConstructorStaticMethodName = string;
+
+/**
+ * Context passed to parser functions
+ * Provides access to configuration and spawn context for advanced parsing scenarios
+ */
+export interface ParserContext<T = any> {
+  /**
+   * The attribute configuration that matched this attribute
+   * Useful for parsers that need to access additional config properties
+   */
+  attrConfig: AttrConfig<T>;
+  
+  /**
+   * The spawn context containing enhancement config and synthesizer element
+   * Useful for parsers that need access to the enhancement or synthesizer context
+   */
+  spawnContext?: SpawnContext<T>;
+  
+  /**
+   * The element being enhanced
+   * Useful for parsers that need to read other attributes or element properties
+   */
+  element: Element;
+  
+  /**
+   * The attribute name that was matched (resolved from template)
+   * Useful for parsers that handle multiple attributes
+   */
+  attrName: string;
+}
+
+/**
+ * Parser function signature
+ * Can accept just the attribute value (simple form) or value + context (advanced form)
+ */
+export type ParserFunction<T = any> = 
+  | ((attrValue: string | null) => any)
+  | ((attrValue: string | null, context?: ParserContext<T>) => any);
+
+export interface AttrConfig<T = unknown, TParserConfig = unknown> {
+  /**
+   * Type of the property value (JSON-serializable string format)
+   */
+  instanceOf?: 'Object' | 'String' | 'Number' | 'Boolean' | 'Array' 
+              | typeof Object | typeof String | typeof Number | typeof Boolean | typeof Array;
+
+  
+  /**
+   * Property name on the spawned class instance to map to
+   * Use '.' to map to the root object using assignGingerly
+   * Is optional.
+   * If not specified, we assume it is the key without the underscore first
+   * character, unless the key is _base in which case it assume mapsTo = "."
+   */
+  mapsTo?: 
+    | '.' 
+    | keyof T 
+    | pathString 
+    | `${pathString} +=`
+    | `${pathString} =!`
+    | `${pathString} -=`
+  
+  /**
+   * Parser to transform attribute string value
+   * - Function: Inline parser function (not JSON serializable)
+   *   - Simple form: (attrValue: string | null) => any
+   *   - Advanced form: (attrValue: string | null, context: ParserContext) => any
+   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'csv')
+   * 
+   * Parser functions can optionally accept a second parameter (ParserContext) which provides:
+   * - attrConfig: The full AttrConfig object for this attribute
+   * - spawnContext: The SpawnContext with enhancement config and synthesizer element
+   * - element: The element being enhanced
+   * - attrName: The resolved attribute name
+   */
+  parser?: 
+    | ParserFunction<T>
+    | string
+  ;
+
+  /**
+   * configuration information needed by a custom parser to properly
+   * parse the attribute.
+   */
+  parserConfig?: TParserConfig;
+  
+  /**
+   * Default value to use when attribute is missing
+   * If defined, bypasses parser when attribute is not present
+   * If undefined, property is not added to initVals when attribute is missing
+   */
+  valIfNull?: any;
+  
+  /**
+   * Enable caching of parsed attribute values
+   * - 'shared': Cache and reuse the same parsed object (fast, but enhancements must not mutate)
+   * - 'cloned': Cache and return a structural clone (safer, but slower)
+   * Note: Parsers should be pure functions when using caching
+   */
+  parseCache?: 'shared' | 'cloned';
+  
+  // /**
+  //  * Whether to only read the initial value (true) or continue observing changes (false)
+  //  * Defaults to true (initial read only)
+  //  */
+  // initialOnly?: boolean;
+
+  /**
+   * Should make sure it is added to static observedAttribrutes
+   */
+  sourceOfTruth?: boolean;
+}
+
+export type AttrPatterns<T = any> = {
+  /**
+   * Base prefix for attribute names
+   */
+  base?: string;
+
+  /**
+   * Configuration for the base pattern
+   */
+  _base?: AttrConfig<T>;
+} & {
+  // Provide autocomplete for all properties of T (optional)
+  [K in keyof T]?: string | AttrConfig<T>;
+} & {
+  // Provide autocomplete for underscore-prefixed config keys
+  [K in keyof T as `_${string & K}`]?: AttrConfig<T>;
+} & {
+  // Allow any other string keys for custom patterns
+  [key: string]: string | AttrConfig<T>;
+};
+
+
+export interface SpawnContext<T = any, TMountContext = any> {
+  config: EnhancementConfig<T>;
+  mountCtx?: TMountContext;
+  /**
+   * Reference to the synthesizer element (be-hive, htmx-container, alpine-scope, etc.)
+   * that contains the EMC script defining this enhancement.
+   * Used for scoped parser registry access during attribute parsing.
+   */
+  synthesizerElement?: Element;
+  /**
+   * The full EMC configuration object that triggered this spawn.
+   * Passed through so enhancement classes can access their full configuration
+   * (including customData) without needing to separately import the JSON file.
+   * This avoids duplicate JSON imports when using emoji shorthand aliases.
+   */
+  emc?: any;
+}
+
+/**
+ * @deprecated Use EnhancementConfig instead
+ */
+export type IEnhancementRegistryItem<T = any> = EnhancementConfig<T>;
+
+/**
+ * Interface for the options passed to assignGingerly
+ */
+export interface IAssignGingerlyOptions {
+  registry?: typeof EnhancementRegistry | EnhancementRegistry;
+  bypassChecks?: boolean;
+  withMethods?: string[] | Set<string>;
+  aka?: Record<string, string>;
+  
+  /**
+   * AbortSignal for cleaning up reactive subscriptions (@eachTime)
+   * Required when using @eachTime symbol for reactive iteration
+   * When the signal is aborted, all event listeners are automatically removed
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Event dispatched when enhancement configs are registered
+ */
+export declare class EnhancementRegisteredEvent extends Event {
+  static eventName: string;
+  config: EnhancementConfig | EnhancementConfig[];
+  constructor(config: EnhancementConfig | EnhancementConfig[]);
+}
+
+/**
+ * Base registry class for managing enhancement configurations
+ * Extends EventTarget to dispatch events when configs are registered
+ */
+export declare class EnhancementRegistry extends EventTarget {
+  push(items: EnhancementConfig | EnhancementConfig[]): void;
+  getItems(): EnhancementConfig[];
+  findBySymbol(symbol: symbol | string): EnhancementConfig | undefined;
+  findByEnhKey(enhKey: string | symbol): EnhancementConfig | undefined;
+}
+
+/**
+ * Constructor signature for ItemScope Manager classes
+ */
+export type ItemscopeManager<T = any> = {
+  new (element: HTMLElement, initVals?: Partial<T>): T;
+}
+
+/**
+ * Configuration for ItemScope Manager registration
+ */
+export interface ItemscopeManagerConfig<T = any> {
+  /**
+   * Manager class constructor
+   */
+  manager: ItemscopeManager<T>;
+  
+  /**
+   * Optional lifecycle method keys
+   * - dispose: Method name to call when manager is disposed
+   * - resolved: Property/event name indicating manager is ready
+   */
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+
+/**
+ * Registry for ItemScope Manager configurations
+ * Extends EventTarget to support lazy registration via events
+ */
+export declare class ItemscopeRegistry extends EventTarget {
+  define(name: string, config: ItemscopeManagerConfig): void;
+  get(name: string): ItemscopeManagerConfig | undefined;
+  whenDefined(name: string): Promise<void>;
+}
+
+/**
+ * Main assignGingerly function
+ */
+export declare function assignGingerly(
+  target: any,
+  source: Record<string | symbol, any>,
+  options?: IAssignGingerlyOptions
+): any;
+
+export default assignGingerly;
+
+export declare class ElementEnhancementGateway{
+  //TODO:  this isn't right
+  enh: ElementEnhancement;
+}
+
+export interface ElementEnhancement{
+  get(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): any;
+  dispose(registryItem: EnhancementConfig | string | symbol): void;
+  whenResolved(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): Promise<any>;
+}

package/types/be-a-beacon/types.d.ts

@@ -0,0 +1,17 @@
+export interface EndUserProps {
+    eventName: string;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    hydrate(self: AP): PAP;
+}

package/types/be-bound/types.d.ts

@@ -0,0 +1,61 @@
+import { Specifier } from "../trans-render/dss/types";
+import {AbsorbingObject, SharingObject} from '../trans-render/asmr/types';
+import { StatementsResult } from "../nested-regex-groups/types";
+
+export interface EndUserProps{
+    bindingRules?: StatementsResult<BindingRule>;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    bindings: Array<Binding>,
+    isParsed?: boolean,
+    rawStatements?: Array<string>
+}
+
+export type SignalEnhancement = 'be-value-added' | 'be-propagating' | undefined;
+
+export interface BindingRule {
+    
+    localProp?: string,
+    localEvent?: string,
+    remoteId?: string,
+    remoteProp?: string,
+    remoteSpecifier?: Specifier,
+
+
+}
+
+export interface Binding {
+    //new and improved
+    localAbsObj: AbsorbingObject;
+    localShareObj: SharingObject;
+    remoteAbsObj: AbsorbingObject;
+    remoteShareObj: SharingObject;
+    //remoteRef: WeakRef<Element>;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+
+export interface Actions{
+    noAttrs(self: AP): ProPAP;
+    getBindings(self: AP): ProPAP;
+    hydrate(self: AP): ProPAP;
+    onRawStatements(self: AP): void;
+}
+
+export type WithStatement = string;
+
+export type BetweenStatement = string;
+
+export type TriggerSource = 'local' | 'remote' | 'tie';
+
+export interface SpecificityResult {
+    val?: any,
+    winner?: TriggerSource;
+}

package/types/be-buttoned-up/types.d.ts

@@ -0,0 +1,19 @@
+export interface EndUserProps{
+    closeOnSelect: boolean;
+    eventName: string;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions{
+    init(self: AllProps, enhancedElement: Element, initVals: PAP): void;
+    hydrate(self: AP): PAP | void
+}

package/types/be-clonable/types.d.ts

@@ -0,0 +1,36 @@
+export interface EndUserProps{
+    triggerInsertPosition: InsertPosition;
+    cloneInsertPosition: InsertPosition;
+    buttonContent: string;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean;
+    trigger: HTMLButtonElement;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface CustomData {
+    triggerSettings: {
+        type: string;
+        '?.classList?.add': string;
+        ariaLabel: string;
+        title: string;
+    },
+    withMethods: string[]
+    
+}
+
+export interface Actions{
+    addCloneBtn(self: AP): ProPAP;
+    setBtnContent(self: AP): void;
+    beCloned(self: AP): void;
+    init(self: AP, enhancedElement: Element, initVals: PAP): Promise<void>
+}

package/types/be-committed/types.d.ts

@@ -0,0 +1,22 @@
+export interface EndUserProps{
+    to: string;
+    nudge: boolean;
+    on: string;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions{
+    
+    hydrate(self: AP): ProPAP;
+    init(self: AP, enhancedElement: Element, initVals: PAP): Promise<void>
+}

package/types/be-decked-with/types.d.ts

@@ -0,0 +1,26 @@
+
+export interface EndUserProps{
+    path: string
+    src: string
+}
+
+export interface AllProps extends EndUserProps{
+    template: HTMLTemplateElement;
+    enhancedElement: Element;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+//export type BAP = AP & BEAllProps;
+
+export interface Actions{
+    act(self: BAP): PAP
+    fetchRemoteTemplate(self: BAP): ProPAP
+    upShadowSearch(self: BAP): ProPAP
+    init(self: BAP, initVals: PAP): Promise<void>
+}

package/types/be-delible/types.d.ts

@@ -0,0 +1,25 @@
+export interface EndUserProps{
+    triggerInsertPosition: InsertPosition;
+    buttonContent: string;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean,
+    trigger: HTMLButtonElement;
+    resolved: boolean,
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions{
+    
+    addDeleteBtn(self: AP): ProPAP ;
+    setBtnContent(self: AP): void;
+    beDeleted(self: AP): void;
+    init(self: AP & Actions, enhancedElement: Element, initVals: PAP): Promise<void>;
+}

package/types/be-reflective/types.d.ts

@@ -0,0 +1,80 @@
+import { SpawnContext } from "../assign-gingerly/types";
+
+/**
+ * Shared context passed via getSharedContext — contains everything
+ * the Reflector needs to self-activate on spawn.
+ */
+export interface ReflectorSharedContext {
+    /** The ElementInternals instance for custom state manipulation */
+    internals: ElementInternals;
+    /** The EventTarget the host dispatches property change events on */
+    hostPropagator: EventTarget;
+}
+
+/**
+ * Context passed to the Reflector feature constructor
+ */
+export interface FeatureSpawnContext extends SpawnContext {
+    key: string;
+    optIn: any;
+    injection: any;
+    featuresRegistry: any;
+    shared?: ReflectorSharedContext;
+}
+
+/**
+ * A single custom state export rule parsed from --custom-state-exports
+ */
+export interface CustomStateRule {
+    /** The custom state name to toggle (e.g. "disabled", "alertTypeIndicatesSuccess") */
+    stateName: string;
+    /** The property name to observe */
+    propName: string;
+    /** The condition type */
+    conditionType: 'boolean' | 'equals' | 'contains' | 'endsWith' | 'modulo' | 'lessThan' | 'greaterThan' | 'lessThanOrEqual' | 'greaterThanOrEqual';
+    /** The comparison value (for non-boolean conditions) */
+    compareValue?: string | number;
+    /** The modulo divisor (for modulo conditions) */
+    moduloDivisor?: number;
+}
+
+/**
+ * Properties that the Reflector feature exposes.
+ * With callbackForwarding, hostPropagator is provided via getSharedContext
+ * and the feature self-activates — but the setter remains for manual use cases.
+ */
+export interface ReflectorProps {
+    /**
+     * The EventTarget that the host element uses to propagate property change events.
+     * Provided via getSharedContext. Also settable post-spawn for reconnection.
+     */
+    hostPropagator: EventTarget | null;
+}
+
+/**
+ * Internal state
+ */
+export interface AllProps extends ReflectorProps {
+    /**
+     * WeakRef to the host custom element
+     */
+    hostRef: WeakRef<HTMLElement> | null;
+
+    /**
+     * The ElementInternals instance from the host (for custom state manipulation)
+     */
+    internals: ElementInternals | null;
+
+    /**
+     * Parsed custom state rules from --custom-state-exports CSS property
+     */
+    rules: CustomStateRule[];
+
+    /**
+     * AbortController for cleaning up event listeners
+     */
+    abortController: AbortController | null;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;

package/types/be-render-neutral/types.d.ts

@@ -0,0 +1,29 @@
+export interface RenderingHTMLScriptElement extends HTMLScriptElement{
+    renderer: (vm: any, html: any) => any,
+}
+
+export interface EndUserProps{
+    vm: any,
+    with: Array<string>,
+}
+
+export type Renderer = (vm: any, html: any) => any;
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    renderer: Renderer,
+    absorbingObject: any
+}
+
+export type PAP = Partial<AllProps>;
+
+export type AP = AllProps;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    getRenderer(self: AP): PAP;
+    doRender(self: AP): void;
+    observe(self: AP): ProPAP;
+    absorb(self: AP, e?: Event): ProPAP;
+}

package/types/be-typed/types.d.ts

@@ -0,0 +1,31 @@
+export interface EndUserProps {
+    triggerInsertPosition: InsertPosition;
+    labelTextContainer: string;
+    buttonContent: string;
+    nudge?: boolean;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean;
+    trigger: WeakRef<HTMLButtonElement>
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+
+
+export interface Actions{
+    addTypeBtn(self: AP): ProPAP;
+    setBtnContent(self: AP): void;
+    openDialog(self: AP): Promise<void>
+}
+
+export interface ITyper{
+    showDialog(): void;
+    dispose(): void;
+}