@aurodesignsystem-dev/auro-formkit 0.0.0-pr1422.0 → 0.0.0-pr1422.2

package/components/input/demo/readme.md

@@ -0,0 +1,134 @@
+<!--
+The README.md file is a compiled document. No edits should be made directly to this file.
+
+README.md is created by running `npm run build:docs`.
+
+This file is generated based on a template fetched from
+`../../docs/templates/componentReadmeTemplate.md`
+and copied to `./componentDocs/README.md` each time the docs are compiled.
+
+The following sections are editable by making changes to the following files:
+
+| SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
+|------------------------|---------------------------------------------------|-------------------------------------|
+| Description            | Description of the component                      | `./docs/partials/description.md`    |
+| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
+| Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
+-->
+
+# Input
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
+<!-- The below content is automatically added from ./docs/partials/description.md -->
+Use the `<auro-input>` custom element to create basic single-line text fields. Supports type `text`, `password`, and `email` with validation, required input, error states and a secondary `bordered` theme. Use the slots `label` and `helpText` for additional content support.
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
+<!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Input Use Cases
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./docs/partials/useCases.md -->
+The `<auro-input>` element should be used in situations where users may:
+
+* needs to enter information
+* be filling out a form
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Getting Started
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ../../docs/templates/componentInstall.md -->
+
+#### NPM Installation
+
+```shell
+$ npm i @aurodesignsystem/auro-formkit
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/gettingStarted.md) -->
+<!-- The below content is automatically added from ../../docs/templates/gettingStarted.md -->
+
+### TypeScript Module Resolution
+
+When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
+
+```json
+{
+    "compilerOptions": {
+        "moduleResolution": "bundler"
+    }
+}
+```
+
+This configuration enables proper module resolution for the component's TypeScript files.
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Install from CDN
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/bundleInstallDescription.md) -->
+<!-- The below content is automatically added from ../../docs/templates/bundleInstallDescription.md -->
+In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-input/+esm"></script>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Formkit Development
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/partials/developmentDescription.md) -->
+<!-- The below content is automatically added from ../../docs/partials/developmentDescription.md -->
+
+### Filtering
+
+Running the `dev` command will open a `localhost` development server for all components in the monorepo at once.
+
+To only develop a single component, use the `--filter` flag:
+
+```shell
+npx turbo dev --filter=@aurodesignsystem/auro-input
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
+
+## Custom Component Registration for Version Management
+
+There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
+
+When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+
+You can do this by importing only the component class and using the `register(name)` method with a unique name:
+
+```js
+// Import the class only
+import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
+
+// Register with a custom name if desired
+AuroInput.register('custom-input');
+```
+
+This will create a new custom element `<custom-input>` that behaves exactly like `<auro-input>`, allowing both to coexist on the same page without interfering with each other.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <custom-input>
+    <span slot="label">Label</span>
+    <span slot="helpText">Help Text</span>
+  </custom-input>
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+
+```html
+  <custom-input>
+    <span slot="label">Label</span>
+    <span slot="helpText">Help Text</span>
+  </custom-input>
+```
+</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:END -->

package/components/input/dist/auro-input.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The `auro-input` element provides users a way to enter data into a text field.
+ * @customElement auro-input
+ *
+ * @slot ariaLabel.clear - Sets aria-label on clear button for screen reader to read
+ * @slot ariaLabel.password.show - Sets aria-label on password button to toggle on showing password
+ * @slot ariaLabel.password.hide - Sets aria-label on password button to toggle off showing password
+ * @slot helpText - Sets the help text displayed below the input.
+ * @slot label - Sets the label text for the input.
+ * @slot optionalLabel - Allows overriding the optional display text "(optional)", which appears next to the label.
+ * @slot displayValue - Allows custom HTML content to display in place of the value when the input is not focused.
+ * @csspart wrapper - Use for customizing the style of the root element
+ * @csspart label - Use for customizing the style of the label element
+ * @csspart helpText - Use for customizing the style of the helpText element
+ * @csspart input - Use for customizing the style of the input element
+ * @csspart accentIcon - Use for customizing the style of the accentIcon element (e.g. credit card icon, calendar icon)
+ * @csspart iconContainer - Use for customizing the style of the iconContainer (e.g. X icon for clearing input value)
+ * @csspart accent-left - Use for customizing the style of the left accent element (e.g. padding, margin)
+ * @csspart accent-right - Use for customizing the style of the right accent element (e.g. padding, margin)
+ * @csspart displayValue - Use for customizing the style of the displayValue element
+ * @csspart inputHelpText - Use for customizing the style of the input help text wrapper
+ */
+export class AuroInput extends BaseInput {
+    static get styles(): import("lit").CSSResult[];
+    /**
+     * This will register this element with the browser.
+     * @param {string} [name="auro-input"] - The name of the element that you want to register.
+     *
+     * @example
+     * AuroInput.register("custom-input") // this will register this element to <custom-input/>
+     *
+     */
+    static register(name?: string): void;
+    /**
+     * @private
+     */
+    private buttonTag;
+    /**
+     * @private
+     */
+    private hasDisplayValueContent;
+    /**
+     * @private
+     */
+    private helpTextTag;
+    /**
+     * @private
+     */
+    private iconTag;
+    /**
+     * @private
+     */
+    private clearButtonRef;
+    /**
+     * Returns classmap configuration for the clear button visibility.
+     * The button is hidden when the input has no value, is read-only, or is disabled.
+     * @private
+     * @returns {Record<string, boolean>} - Classmap object controlling clear button display state.
+     */
+    private get clearBtnClassMap();
+    /**
+     * Determines if the HTML input element should be visually hidden.
+     * Returns true when display value content exists without focus and has a value,
+     * or when the input has no value, is not focused, and has no placeholder text.
+     * @returns {boolean} - True if the input should be visually hidden, false otherwise.
+     * @private
+     */
+    private get inputHidden();
+    /**
+     * Determines if the input should display in a state with no focus or value indication.
+     * Returns true when the input has display content without focus and has a value,
+     * or when the input has no value and is not focused.
+     * @returns {boolean} - True if the input should show no focus or value state, false otherwise.
+     * @private
+     */
+    private get noFocusOrValue();
+    /**
+     * Whether the label is being hidden currently based on state.
+     * @returns {boolean} - Returns true if the label is hidden.
+     * @private
+     */
+    private get labelHidden();
+    /**
+     * Returns the label font class based on layout and visibility state.
+     * @private
+     * @returns {string} - The font class for the label.
+     */
+    private get labelFontClass();
+    /**
+     * Returns the input font class based on layout and visibility state.
+     * @private
+     * @returns {string} - The font class for the input.
+     */
+    private get inputFontClass();
+    /**
+     * Returns classmap configuration for html5 input labels in all layouts.
+     * @private
+     * @returns {Record<string, boolean>}
+     */
+    private get commonLabelClasses();
+    /**
+     * Returns classmap configuration for html5 inputs in all layouts.
+     * @private
+     * @returns {Record<string, boolean>} - Returns classmap.
+     */
+    private get commonInputClasses();
+    /**
+     * Common display value wrapper classes.
+     * @private
+     * @returns {Record<string, boolean>}
+     */
+    private get commonDisplayValueWrapperClasses();
+    /**
+     * Returns classmap configuration for html5 inputs in each layout.
+     * @private
+     * @returns {object} - Returns classmap.
+     */
+    private get legacyInputClasses();
+    /**
+     * Returns classmap configuration for wrapper elements in each layout.
+     * @private
+     * @returns {object} - Returns classmap.
+     */
+    private get commonWrapperClasses();
+    /**
+     * Returns classmap configuration for helpText elements in each layout.
+     * @private
+     * @returns {object} - Returns classmap.
+     */
+    private get helpTextClasses();
+    /**
+     * Function to determine if the input is meant to render an icon visualizing the input type.
+     * @private
+     * @returns {boolean} - Returns true if the input type is meant to render an icon.
+     */
+    private hasTypeIcon;
+    /**
+     * Function to determine if there is any displayValue content to render.
+     * @private
+     * @returns {void}
+     */
+    private checkDisplayValueSlotChange;
+    clearBtn: Element;
+    /**
+     * Returns HTML for the validation error icon.
+     * @private
+     * @returns {html} - Returns HTML for the validation error icon.
+     */
+    private renderValidationErrorIconHtml;
+    /**
+     * Returns HTML for the HTML5 input element.
+     * @private
+     * @param {boolean} [useLegacyHiddenState=false] - If true, the input will be visually hidden when not focused and has no value.
+     * @returns {html} - Returns HTML for the HTML5 input element.
+     */
+    private renderHtmlInput;
+    /**
+     * Returns HTML for the clear action button.
+     * @private
+     * @returns {html} - Returns HTML for the clear action button.
+     */
+    private renderHtmlActionClear;
+    /**
+     * Returns HTML for the show password button.
+     * @private
+     * @returns {html} - Returns HTML for the show password button.
+     */
+    private renderHtmlNotificationPassword;
+    /**
+     * Returns HTML for the input type icon.
+     * @private
+     * @returns {html} - Returns HTML for the input type icon.
+     */
+    private renderHtmlTypeIcon;
+    /**
+     * Returns HTML for the help text and error message.
+     * @private
+     * @returns {html} - Returns HTML for the help text and error message.
+     */
+    private renderHtmlHelpText;
+    /**
+     * Returns HTML for the classic layout.
+     * @private
+     * @returns {import("lit").TemplateResult} - Returns HTML for the classic layout.
+     */
+    private renderLayoutClassic;
+    /**
+     * Returns HTML for the emphasized layout. Does not support type="*".
+     * @private
+     * @returns {html} - Returns HTML for the emphasized layout.
+     */
+    private renderLayoutEmphasized;
+    /**
+     * Returns HTML for the emphasized layout. Does not support type="*".
+     * @private
+     * @returns {html} - Returns HTML for the emphasized layout.
+     */
+    private renderLayoutSnowflake;
+    /**
+     * Logic to determine the layout of the component.
+     * @private
+     * @param {string} [ForcedLayout] - Used to force a specific layout, pass in the layout name to use.
+     * @returns {void}
+     */
+    private renderLayout;
+}
+import BaseInput from './base-input.js';