feat(react): prop aliases

emdgroup-liquid · May 21, 2021 · 4165e23 · 4165e23
1 parent b1f01be
commit 4165e23
Show file tree

Hide file tree

Showing 16 changed files with 113 additions and 101 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -15,6 +15,7 @@ const commonTSConfig = {
     '@stencil/strict-boolean-conditions': 0,
     '@stencil/element-type': 0,
     '@stencil/decorators-style': 0,
+    '@stencil/strict-mutable': 0,
     'react/jsx-no-bind': 0,
   },
 }

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -129,22 +129,47 @@ makes it hard to purge unused CSS; hense we depend on namespacing.
   ```tsx
   import { Component, h } from '@stencil/core'
   @Component({
-    tag: 'ld-button',
-    styleUrl: 'ld-button.css',
+    tag: 'ld-my-component',
+    styleUrl: 'ld-my-component.css',
     shadow: false,
   })
-  export class LdButton {
+  export class LdMyComponent {
     render() {
       return (
-        <button class="ld-button">
+        <div class="ld-my-component">
           <slot />
-        </button>
+        </div>
       )
     }
   }
   ```
   It applies the CSS class `ld-button` to its root element. Now the consuming developer can decide   on either using the WebComponent `<ld-button>Submit</ld-button>` or the CSS class directly
   `<button class="ld-button">Submit</ld-button>`.
+- In order for camelcase props to work in React based apps, we create lowercase aliases in components, which have camelcase props, by adding the `@Element()` decorator to the component, making all camelcase props mutable and calling the utility function `applyPropAliases` in the `componentWillLoad` hook: 
+  ```tsx
+  import { Component, h } from '@stencil/core'
+  import { applyPropAliases } from '../../utils/applyPropAliases'
+  @Component({
+    tag: 'ld-my-component',
+    styleUrl: 'ld-my-component.css',
+    shadow: false,
+  })
+  export class LdMyComponent {
+    @Element() el: HTMLDivElement
+    @Prop({ mutable: true })
+    myCamelcaseProp: string
+    componentWillLoad() {
+      applyPropAliases.apply(this)
+    }
+    render() {
+      return (
+        <div class="ld-my-component">
+          <slot />
+        </div>
+      )
+    }
+  }
+  ```
 - We enable type checking and intelliSense for Web Component attributes by importing the autogenerated components type definitions file (src/components.d.ts) at the top of all imports in each component: 
   ```tsx
   import '../../../components' // type definitions for type checks and intelliSense

diff --git a/src/docs/components/docs-btn-toggle-nav/docs-btn-toggle-nav.tsx b/src/docs/components/docs-btn-toggle-nav/docs-btn-toggle-nav.tsx
@@ -34,7 +34,6 @@ export class DocsBtnToggleNav {
     passive: false,
   })
   handleKeyDown(ev: KeyboardEvent) {
-    console.info('ev.key', ev.key)
     if (ev.key === ' ') {
       ev.stopImmediatePropagation()
       ev.preventDefault()

diff --git a/src/docs/components/docs-main/docs-main.css b/src/docs/components/docs-main/docs-main.css
@@ -235,6 +235,11 @@
     > h5,
     > h6 {
       font-weight: 900;
+
+      > code {
+        font-size: inherit;
+        font-weight: inherit;
+      }
     }
 
     > ul,

diff --git a/src/docs/components/docs-search/docs-search.tsx b/src/docs/components/docs-search/docs-search.tsx
@@ -110,7 +110,7 @@ export class DocsSearch {
               ref={(el) => (this.searchInput = el as HTMLLdInputElement)}
               type="search"
               mode="light"
-              spellcheck="false"
+              spellcheck={false}
             ></ld-input>
           </form>
           {this.results.length ? (

diff --git a/src/liquid/components/ld-button/ld-button.tsx b/src/liquid/components/ld-button/ld-button.tsx
@@ -4,6 +4,7 @@ import { cloneAttributes } from '../../utils/cloneAttributes'
 import { JSXBase } from '@stencil/core/internal'
 import ButtonHTMLAttributes = JSXBase.ButtonHTMLAttributes
 import AnchorHTMLAttributes = JSXBase.AnchorHTMLAttributes
+import { applyPropAliases } from '../../utils/applyPropAliases'
 
 @Component({
   tag: 'ld-button',
@@ -25,10 +26,10 @@ export class LdButton {
   @Prop() mode?: 'highlight' | 'secondary' | 'ghost' | 'danger'
 
   /** Align text. */
-  @Prop() alignText: 'left' | 'right'
+  @Prop({ mutable: true }) alignText: 'left' | 'right'
 
   /** Justify content. */
-  @Prop() justifyContent: 'start' | 'end' | 'between'
+  @Prop({ mutable: true }) justifyContent: 'start' | 'end' | 'between'
 
   /**
    * Transforms the button to an anchor element.
@@ -51,6 +52,10 @@ export class LdButton {
     }
   }
 
+  componentWillLoad() {
+    applyPropAliases.apply(this)
+  }
+
   render() {
     let cl = 'ld-button ld-theme-bg-primary ld-theme-bg-primary--interactive'
     if (this.size) cl += ` ld-button--${this.size}`

diff --git a/src/liquid/components/ld-button/readme.md b/src/liquid/components/ld-button/readme.md
@@ -263,23 +263,6 @@ If you'd rather like to use the CSS component on a regular button element, inspe
 | `target`         | `target`          | The `target` attributed can be used in conjunction with the `href` attribute. See [mdn docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target) for more information on the `target` attribute. | `"_blank" \| "_parent" \| "_self" \| "_top"`        | `undefined` |
 
 
-## Dependencies
-
-### Used by
-
- - docs-copy-to-cb
- - docs-edit-on-github
- - docs-toggle-code
-
-### Graph
-```mermaid
-graph TD;
-  docs-copy-to-cb --> ld-button
-  docs-edit-on-github --> ld-button
-  docs-toggle-code --> ld-button
-  style ld-button fill:#f9f,stroke:#333,stroke-width:4px
-```
-
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*
diff --git a/src/liquid/components/ld-heading/ld-heading.tsx b/src/liquid/components/ld-heading/ld-heading.tsx
@@ -1,18 +1,27 @@
-import { Component, h, Prop } from '@stencil/core'
+import { Component, Element, h, Prop } from '@stencil/core'
+import { cloneAttributes } from '../../utils/cloneAttributes'
+import { JSXBase } from '@stencil/core/internal'
+import HeadingHTMLAttributes = JSXBase.HTMLAttributes
+import { applyPropAliases } from '../../utils/applyPropAliases'
 
 @Component({
   tag: 'ld-heading',
   styleUrl: 'ld-heading.css',
   shadow: false,
 })
 export class LdHeading {
+  @Element() el: HTMLHeadingElement
+
   /** The heading level. */
   @Prop() level!: 1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'
 
   /**
    * The heading style. Overrides the style inferred from the heading level.
    */
-  @Prop() visualLevel:
+  @Prop({
+    mutable: true,
+  })
+  visualLevel:
     | undefined
     | 'h1'
     | 'h2'
@@ -41,7 +50,8 @@ export class LdHeading {
    * Since b1 to b6 headings are uppercase headings, screen readers need to be served a
    * (non-uppercase) aria-label (otherwise they will read out the heading letter by letter).
    */
-  @Prop() ariaLabel: string | undefined
+  @Prop({ mutable: true })
+  ariaLabel: string | undefined
 
   private validateLevel(newValue: number | string) {
     if (![1, 2, 3, 4, 5, 6].includes(parseInt(newValue + '', 10))) {
@@ -90,6 +100,8 @@ export class LdHeading {
   }
 
   componentWillLoad() {
+    applyPropAliases.apply(this)
+
     this.validateLevel(this.level)
     this.validateVisualLevel(this.visualLevel)
   }
@@ -99,7 +111,11 @@ export class LdHeading {
     const cl = `ld-heading ld-heading--${this.visualLevel || 'h' + this.level}`
 
     return (
-      <HTag class={cl} aria-label={this.ariaLabel}>
+      <HTag
+        class={cl}
+        aria-label={this.ariaLabel}
+        {...cloneAttributes<HeadingHTMLAttributes<HTMLHeadingElement>>(this.el)}
+      >
         <slot></slot>
       </HTag>
     )

diff --git a/src/liquid/components/ld-heading/readme.md b/src/liquid/components/ld-heading/readme.md
@@ -128,19 +128,6 @@ If you'd rather like to use the CSS component, inspect and copy the markup and C
 | `visualLevel`        | `visual-level` | The heading style. Overrides the style inferred from the heading level.                                                                                                                                                                                     | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "b1" \| "b2" \| "b3" \| "b4" \| "b5" \| "b6" \| "xb1" \| "xb2" \| "xb3" \| "xh1" \| "xh2" \| "xh3" \| "xh4" \| "xh5" \| "xh6"` | `undefined` |
 
 
-## Dependencies
-
-### Used by
-
- - docs-nav
-
-### Graph
-```mermaid
-graph TD;
-  docs-nav --> ld-heading
-  style ld-heading fill:#f9f,stroke:#333,stroke-width:4px
-```
-
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*
diff --git a/src/liquid/components/ld-icon/readme.md b/src/liquid/components/ld-icon/readme.md
@@ -65,23 +65,6 @@ Liquid's icons use the [`currentColor`](https://developer.mozilla.org/en-US/docs
 |      | (optional) Custom SVG icon (only valid without name prop). |
 
 
-## Dependencies
-
-### Used by
-
- - docs-copy-to-cb
- - docs-edit-on-github
- - docs-toggle-code
-
-### Graph
-```mermaid
-graph TD;
-  docs-copy-to-cb --> ld-icon
-  docs-edit-on-github --> ld-icon
-  docs-toggle-code --> ld-icon
-  style ld-icon fill:#f9f,stroke:#333,stroke-width:4px
-```
-
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*
diff --git a/src/liquid/components/ld-input/ld-input.css b/src/liquid/components/ld-input/ld-input.css
@@ -1,6 +1,8 @@
+/*
 :where(.ld-input) {
   width: 12rem;
 }
+*/
 
 .ld-input {
   --ld-input-padding-x: 0.625rem;
@@ -14,6 +16,7 @@
   box-shadow: inset 0 0 0 0.1rem var(--ld-col-rblck1);
   max-width: 100%;
   border-radius: var(--ld-sp-4);
+  line-height: 1;
 
   > :where(:not(input)) {
     user-select: none;
@@ -67,7 +70,8 @@
       }
 
       &.ld-button--sm {
-        margin-left: var(--ld-sp-4);
+        margin: var(--ld-sp-4);
+        margin-right: 0;
       }
     }
 
@@ -81,7 +85,8 @@
       }
 
       &.ld-button--sm {
-        margin-right: var(--ld-sp-4);
+        margin: var(--ld-sp-4);
+        margin-left: 0;
       }
     }
 

diff --git a/src/liquid/components/ld-input/ld-input.tsx b/src/liquid/components/ld-input/ld-input.tsx
@@ -9,12 +9,12 @@ import InputHTMLAttributes = JSXBase.InputHTMLAttributes
  * and the `ld-input-message` component. See examples in the docs for a better
  * understanding on how they can be used together.
  *
- * @slot item-start - The purpose of this slot is to add icons or buttons
+ * @slot start - The purpose of this slot is to add icons or buttons
  * to the input, __justifying the item to the end of the component__.
  * Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component.
  * If you choose to place something different into the slot, you will probably
  * need to adjust some styles on the slotted item in order to make it fit right.
- * @slot item-end - The purpose of this slot is to add icons or buttons
+ * @slot end - The purpose of this slot is to add icons or buttons
  * to the input, __justifying the item to the start of the component__.
  * Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component.
  * If you choose to place something different into the slot, you will probably
@@ -78,16 +78,18 @@ export class LdInput {
 
     return (
       <Host class={cl} onClick={this.handleClick.bind(this)}>
-        <slot name="item-start"></slot>
+        <slot name="start"></slot>
         <input
           ref={(el) => (this.input = el as HTMLInputElement)}
           onInput={this.handleInput.bind(this)}
+          placeholder={this.placeholder}
+          type={this.type}
           onBlur={this.handleBlur.bind(this)}
           onFocus={this.handleFocus.bind(this)}
           {...cloneAttributes<InputHTMLAttributes<HTMLInputElement>>(this.el)}
           value={this.value}
         />
-        <slot name="item-end"></slot>
+        <slot name="end"></slot>
       </Host>
     )
   }

diff --git a/src/liquid/components/ld-input/readme.md b/src/liquid/components/ld-input/readme.md
@@ -160,6 +160,14 @@ You can use [slots](#slots) in order to add static or interactive elements, such
 </ld-input>
 {% endexample %}
 
+#### With custom component
+
+{% example %}
+<ld-input placeholder="Placeholder">
+  <span slot="item-end">🤓</span>
+</ld-input>
+{% endexample %}
+
 ### Input validation
 
 The `ld-input` component does not provide any properties or methods for validating the input value internally. Instead, it provides a low level API for integrating the component with the form validation solution of your choice. It allows you to listen for `focus`, `input` and `blur` events and setting error / info messages via the [`ld-input-message`](/liquid/components/ld-input-message/) component. The following is an example on how you could implement form validation with vanilla JS:
@@ -265,24 +273,11 @@ The `ld-input` component does not provide any properties or methods for validati
 
 ## Slots
 
-| Slot           | Description                                                                                                                                                                                                                                                                                                                                                           |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"item-end"`   | The purpose of this slot is to add icons or buttons to the input, __justifying the item to the start of the component__. Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component. If you choose to place something different into the slot, you will probably need to adjust some styles on the slotted item in order to make it fit right. |
-| `"item-start"` | The purpose of this slot is to add icons or buttons to the input, __justifying the item to the end of the component__. Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component. If you choose to place something different into the slot, you will probably need to adjust some styles on the slotted item in order to make it fit right.   |
-
-
-## Dependencies
-
-### Used by
-
- - docs-search
+| Slot      | Description                                                                                                                                                                                                                                                                                                                                                           |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"end"`   | The purpose of this slot is to add icons or buttons to the input, __justifying the item to the start of the component__. Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component. If you choose to place something different into the slot, you will probably need to adjust some styles on the slotted item in order to make it fit right. |
+| `"start"` | The purpose of this slot is to add icons or buttons to the input, __justifying the item to the end of the component__. Styling for `ld-icon` and `ld-button` is provided within the `ld-input` component. If you choose to place something different into the slot, you will probably need to adjust some styles on the slotted item in order to make it fit right.   |
 
-### Graph
-```mermaid
-graph TD;
-  docs-search --> ld-input
-  style ld-input fill:#f9f,stroke:#333,stroke-width:4px
-```
 
 ----------------------------------------------
 

diff --git a/src/liquid/components/ld-sr-only/readme.md b/src/liquid/components/ld-sr-only/readme.md
@@ -30,23 +30,6 @@ The CSS class sr-only works the same way as its web component counterpart, excep
 <!-- Auto Generated Below -->
 
 
-## Dependencies
-
-### Used by
-
- - docs-copy-to-cb
- - docs-pick-theme
- - docs-toggle-code
-
-### Graph
-```mermaid
-graph TD;
-  docs-copy-to-cb --> ld-sr-only
-  docs-pick-theme --> ld-sr-only
-  docs-toggle-code --> ld-sr-only
-  style ld-sr-only fill:#f9f,stroke:#333,stroke-width:4px
-```
-
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*