@hypothesis/frontend-shared - npm Package Compare versions

Comparing version 4.5.0 to 4.5.2

lib/components/containers.d.ts

 /**
+ * Components for laying out content within a consistently-styled container
+ */
+/**
  * @typedef {import('preact').ComponentChildren} Children
+ * @typedef {import('preact').JSX.HTMLAttributes<HTMLDivElement>} HTMLDivAttributes
+ * @typedef {import('preact').Ref<HTMLElement>} ElementRef
+ */
+/**
+ * @typedef CommonPresentationalProps
+ * @prop {Children} [children]
+ * @prop {string|string[]} [classes] - Optional extra CSS classes to append to
+ *   the component's default classes
+ * @prop {ElementRef} [containerRef] - Deprecated; use
+ *   `elementRef` instead.
+ * @prop {ElementRef} [elementRef]
  *
- * @typedef ContainerProps
- * @prop {Children} children
- * @prop {string} [classes] - Additional CSS classes to apply
- * @prop {import('preact').Ref<HTMLElement>} [containerRef] - Access to the
- *  wrapping element.
+ * @typedef {HTMLDivAttributes & CommonPresentationalProps} PresentationalProps
  */
@@ -13,62 +23,46 @@ /**
  *
- * @param {ContainerProps} props
+ * @param {PresentationalProps} props
  */
-export function Frame({ children, classes, containerRef }: ContainerProps): import("preact").JSX.Element;
+export function Frame({ children, classes, containerRef, elementRef, ...restProps }: PresentationalProps): import("preact").JSX.Element;
 /**
  * Render content inside of a "card"
  *
- * @param {ContainerProps} props
+ * @param {PresentationalProps} props
  */
-export function Card({ children, classes, containerRef }: ContainerProps): import("preact").JSX.Element;
+export function Card({ children, classes, containerRef, elementRef, ...restProps }: PresentationalProps): import("preact").JSX.Element;
 /**
- *
- * @typedef ActionBaseProps
- * @prop {'row'|'column'} [direction='row'] - Lay out the actions horizontally (row)
- *   or vertically (column)
- */
-/**
  * Render a set of actions (typically buttons) laid out either horizontally
  * by default or vertically.
  *
- * @param {ActionBaseProps & ContainerProps} props
+ * @param {{ direction?: 'row'|'column'} & PresentationalProps} props
  */
-export function Actions({ children, direction, classes, containerRef, }: ActionBaseProps & ContainerProps): import("preact").JSX.Element;
+export function Actions({ children, direction, classes, containerRef, elementRef, ...restProps }: {
+    direction?: 'row' | 'column';
+} & PresentationalProps): import("preact").JSX.Element;
 /**
- *
- * @typedef ScrollboxBaseProps
- * @prop {boolean} [withHeader=false] - Provide layout affordances for a sticky
- *   header in the scrollable content
- */
-/**
  * Render a scrollable container to contain content that might overflow.
+ * Optionally provide styling affordances for a sticky header (`withHeader`).
  *
- * @param {ScrollboxBaseProps & ContainerProps} props
+ * @param {{withHeader?: boolean} & PresentationalProps} props
  */
-export function Scrollbox({ children, classes, containerRef, withHeader, }: ScrollboxBaseProps & ContainerProps): import("preact").JSX.Element;
+export function Scrollbox({ children, classes, containerRef, elementRef, withHeader, ...restProps }: {
+    withHeader?: boolean;
+} & PresentationalProps): import("preact").JSX.Element;
 export type Children = import('preact').ComponentChildren;
-export type ContainerProps = {
-    children: Children;
+export type HTMLDivAttributes = import('preact').JSX.HTMLAttributes<HTMLDivElement>;
+export type ElementRef = import('preact').Ref<HTMLElement>;
+export type CommonPresentationalProps = {
+    children?: Children;
     /**
-     * - Additional CSS classes to apply
+     * - Optional extra CSS classes to append to
+     * the component's default classes
      */
-    classes?: string | undefined;
+    classes?: string | string[] | undefined;
     /**
-     * - Access to the
-     * wrapping element.
+     * - Deprecated; use
+     * `elementRef` instead.
      */
     containerRef?: import("preact").Ref<HTMLElement> | undefined;
+    elementRef?: import("preact").Ref<HTMLElement> | undefined;
 };
-export type ActionBaseProps = {
-    /**
-     * - Lay out the actions horizontally (row)
-     * or vertically (column)
-     */
-    direction?: "row" | "column" | undefined;
-};
-export type ScrollboxBaseProps = {
-    /**
-     * - Provide layout affordances for a sticky
-     * header in the scrollable content
-     */
-    withHeader?: boolean | undefined;
-};
+export type PresentationalProps = HTMLDivAttributes & CommonPresentationalProps;

lib/components/containers.js

 var _jsxFileName = "/home/runner/work/frontend-shared/frontend-shared/src/components/containers.js";
-
+import classnames from 'classnames';
+import { downcastRef } from '../util/typing';
 /**
  * Components for laying out content within a consistently-styled container
  */
-import classnames from 'classnames';
-import { downcastRef } from '../util/typing';
+
 /**
  * @typedef {import('preact').ComponentChildren} Children
+ * @typedef {import('preact').JSX.HTMLAttributes<HTMLDivElement>} HTMLDivAttributes
+ * @typedef {import('preact').Ref<HTMLElement>} ElementRef
+ */
+
+/**
+ * @typedef CommonPresentationalProps
+ * @prop {Children} [children]
+ * @prop {string|string[]} [classes] - Optional extra CSS classes to append to
+ *   the component's default classes
+ * @prop {ElementRef} [containerRef] - Deprecated; use
+ *   `elementRef` instead.
+ * @prop {ElementRef} [elementRef]
  *
- * @typedef ContainerProps
- * @prop {Children} children
- * @prop {string} [classes] - Additional CSS classes to apply
- * @prop {import('preact').Ref<HTMLElement>} [containerRef] - Access to the
- *  wrapping element.
+ * @typedef {HTMLDivAttributes & CommonPresentationalProps} PresentationalProps
  */
@@ -21,3 +29,3 @@
  *
- * @param {ContainerProps} props
+ * @param {PresentationalProps} props
  */
@@ -28,12 +36,15 @@
   children,
-  classes = '',
-  containerRef
+  classes,
+  containerRef,
+  elementRef,
+  ...restProps
 }) {
   return _jsxDEV("div", {
     className: classnames('Hyp-Frame', classes),
-    ref: downcastRef(containerRef),
+    ...restProps,
+    ref: downcastRef(elementRef !== null && elementRef !== void 0 ? elementRef : containerRef),
     children: children
   }, void 0, false, {
     fileName: _jsxFileName,
-    lineNumber: 26,
+    lineNumber: 40,
     columnNumber: 5
@@ -45,3 +56,3 @@ }, this);
  *
- * @param {ContainerProps} props
+ * @param {PresentationalProps} props
  */
@@ -51,12 +62,15 @@
   children,
-  classes = '',
-  containerRef
+  classes,
+  containerRef,
+  elementRef,
+  ...restProps
 }) {
   return _jsxDEV("div", {
     className: classnames('Hyp-Card', classes),
-    ref: downcastRef(containerRef),
+    ...restProps,
+    ref: downcastRef(elementRef !== null && elementRef !== void 0 ? elementRef : containerRef),
     children: children
   }, void 0, false, {
     fileName: _jsxFileName,
-    lineNumber: 42,
+    lineNumber: 63,
     columnNumber: 5
@@ -66,13 +80,6 @@ }, this);
 /**
- *
- * @typedef ActionBaseProps
- * @prop {'row'|'column'} [direction='row'] - Lay out the actions horizontally (row)
- *   or vertically (column)
- */
-
-/**
  * Render a set of actions (typically buttons) laid out either horizontally
  * by default or vertically.
  *
- * @param {ActionBaseProps & ContainerProps} props
+ * @param {{ direction?: 'row'|'column'} & PresentationalProps} props
  */
@@ -83,4 +90,6 @@
   direction = 'row',
-  classes = '',
-  containerRef
+  classes,
+  containerRef,
+  elementRef,
+  ...restProps
 }) {
@@ -90,7 +99,8 @@ const baseClass = `Hyp-Actions--${direction}`;
     className: classnames(baseClass, classes),
-    ref: downcastRef(containerRef),
+    ...restProps,
+    ref: downcastRef(elementRef !== null && elementRef !== void 0 ? elementRef : containerRef),
     children: children
   }, void 0, false, {
     fileName: _jsxFileName,
-    lineNumber: 72,
+    lineNumber: 89,
     columnNumber: 5
@@ -100,12 +110,6 @@ }, this);
 /**
- *
- * @typedef ScrollboxBaseProps
- * @prop {boolean} [withHeader=false] - Provide layout affordances for a sticky
- *   header in the scrollable content
- */
-
-/**
  * Render a scrollable container to contain content that might overflow.
+ * Optionally provide styling affordances for a sticky header (`withHeader`).
  *
- * @param {ScrollboxBaseProps & ContainerProps} props
+ * @param {{withHeader?: boolean} & PresentationalProps} props
  */
@@ -115,5 +119,7 @@
   children,
-  classes = '',
+  classes,
   containerRef,
-  withHeader = false
+  elementRef,
+  withHeader = false,
+  ...restProps
 }) {
@@ -123,7 +129,8 @@ const baseClass = withHeader ? 'Hyp-Scrollbox--with-header' : 'Hyp-Scrollbox';
     className: classnames(baseClass, classes),
-    ref: downcastRef(containerRef),
+    ...restProps,
+    ref: downcastRef(elementRef !== null && elementRef !== void 0 ? elementRef : containerRef),
     children: children
   }, void 0, false, {
     fileName: _jsxFileName,
-    lineNumber: 101,
+    lineNumber: 115,
     columnNumber: 5
@@ -130,0 +137,0 @@ }, this);

lib/components/Table.js

@@ -184,3 +184,3 @@ var _jsxFileName = "/home/runner/work/frontend-shared/frontend-shared/src/components/Table.js";
     classes: classnames('Hyp-Table-Scrollbox', containerClasses),
-    containerRef: scrollboxRef,
+    elementRef: scrollboxRef,
     children: [_jsxDEV("table", {
@@ -187,0 +187,0 @@ "aria-label": accessibleLabel,

lib/pattern-library/components/patterns/ColorFoundations.js

@@ -144,2 +144,34 @@ var _jsxFileName = "/home/runner/work/frontend-shared/frontend-shared/src/pattern-library/components/patterns/ColorFoundations.js";
 
+const slateExamples = _jsxDEV(_Fragment, {
+  children: [_jsxDEV(ColorSwatch, {
+    colorClass: "bg-slate-1",
+    colorName: "slate-1"
+  }, void 0, false, {
+    fileName: _jsxFileName,
+    lineNumber: 41,
+    columnNumber: 5
+  }, this), _jsxDEV(ColorSwatch, {
+    colorClass: "bg-slate-3",
+    colorName: "slate-3"
+  }, void 0, false, {
+    fileName: _jsxFileName,
+    lineNumber: 42,
+    columnNumber: 5
+  }, this), _jsxDEV(ColorSwatch, {
+    colorClass: "bg-slate-5",
+    colorName: "slate-5"
+  }, void 0, false, {
+    fileName: _jsxFileName,
+    lineNumber: 43,
+    columnNumber: 5
+  }, this), _jsxDEV(ColorSwatch, {
+    colorClass: "bg-slate-7",
+    colorName: "slate-7"
+  }, void 0, false, {
+    fileName: _jsxFileName,
+    lineNumber: 44,
+    columnNumber: 5
+  }, this)]
+}, void 0, true);
+
 const stateExamples = _jsxDEV(_Fragment, {
@@ -151,3 +183,3 @@ children: [_jsxDEV(ColorSwatch, {
     fileName: _jsxFileName,
-    lineNumber: 41,
+    lineNumber: 50,
     columnNumber: 5
@@ -159,3 +191,3 @@ }, this), _jsxDEV(ColorSwatch, {
     fileName: _jsxFileName,
-    lineNumber: 42,
+    lineNumber: 51,
     columnNumber: 5
@@ -167,3 +199,3 @@ }, this), _jsxDEV(ColorSwatch, {
     fileName: _jsxFileName,
-    lineNumber: 43,
+    lineNumber: 52,
     columnNumber: 5
@@ -183,3 +215,3 @@ }, this)]
         fileName: _jsxFileName,
-        lineNumber: 51,
+        lineNumber: 60,
         columnNumber: 9
@@ -189,3 +221,3 @@ }, this)
       fileName: _jsxFileName,
-      lineNumber: 50,
+      lineNumber: 59,
       columnNumber: 7
@@ -199,3 +231,3 @@ }, this), _jsxDEV(Library.Pattern, {
         fileName: _jsxFileName,
-        lineNumber: 55,
+        lineNumber: 64,
         columnNumber: 9
@@ -205,5 +237,25 @@ }, this)
       fileName: _jsxFileName,
-      lineNumber: 54,
+      lineNumber: 63,
       columnNumber: 7
     }, this), _jsxDEV(Library.Pattern, {
+      title: "Slates",
+      children: [_jsxDEV("p", {
+        children: "These slightly blue greys may be used sparingly to help with differentiation and clarity within interfaces."
+      }, void 0, false, {
+        fileName: _jsxFileName,
+        lineNumber: 68,
+        columnNumber: 9
+      }, this), _jsxDEV("div", {
+        className: "flex flex-row flex-wrap gap-4",
+        children: slateExamples
+      }, void 0, false, {
+        fileName: _jsxFileName,
+        lineNumber: 72,
+        columnNumber: 9
+      }, this)]
+    }, void 0, true, {
+      fileName: _jsxFileName,
+      lineNumber: 67,
+      columnNumber: 7
+    }, this), _jsxDEV(Library.Pattern, {
       title: "State indicators",
@@ -215,3 +267,3 @@ children: _jsxDEV("div", {
         fileName: _jsxFileName,
-        lineNumber: 59,
+        lineNumber: 76,
         columnNumber: 9
@@ -221,3 +273,3 @@ }, this)
       fileName: _jsxFileName,
-      lineNumber: 58,
+      lineNumber: 75,
       columnNumber: 7
@@ -227,3 +279,3 @@ }, this)]
     fileName: _jsxFileName,
-    lineNumber: 49,
+    lineNumber: 58,
     columnNumber: 5
@@ -230,0 +282,0 @@ }, this);

lib/pattern-library/components/patterns/IconFoundations.js

@@ -22,3 +22,3 @@ var _jsxFileName = "/home/runner/work/frontend-shared/frontend-shared/src/pattern-library/components/patterns/IconFoundations.js";
         children: Object.keys(icons).map(iconName => _jsxDEV(Card, {
-          classes: "flex flex-col items-center bg-grey-0 border-[#9c9cab] space-y-3 rounded-lg",
+          classes: "flex flex-col items-center bg-grey-0 border-slate-5 space-y-3 rounded-lg",
           children: [_jsxDEV("div", {
@@ -25,0 +25,0 @@ style: "text-lg",

lib/tailwind.preset.d.ts

@@ -12,12 +12,20 @@ declare namespace _default {
                 black: any;
-                'grey-0': string;
-                'grey-1': string;
-                'grey-2': string;
-                'grey-3': string;
-                'grey-4': string;
-                'grey-5': string;
-                'grey-6': string;
-                'grey-7': string;
-                'grey-8': string;
-                'grey-9': string;
+                grey: {
+                    0: string;
+                    1: string;
+                    2: string;
+                    3: string;
+                    4: string;
+                    5: string;
+                    6: string;
+                    7: string;
+                    8: string;
+                    9: string;
+                };
+                slate: {
+                    1: string;
+                    3: string;
+                    5: string;
+                    7: string;
+                };
                 green: {
@@ -24,0 +32,0 @@ success: string;

lib/tailwind.preset.js

@@ -14,12 +14,22 @@ import plugin from 'tailwindcss/plugin.js';
         black: colors.black,
-        'grey-0': '#fafafa',
-        'grey-1': '#f2f2f2',
-        'grey-2': '#ececec',
-        'grey-3': '#dbdbdb',
-        'grey-4': '#a6a6a6',
-        'grey-5': '#9c9c9c',
-        'grey-6': '#737373',
-        'grey-7': '#595959',
-        'grey-8': '#3f3f3f',
-        'grey-9': '#202020',
+        grey: {
+          0: '#fafafa',
+          1: '#f2f2f2',
+          2: '#ececec',
+          3: '#dbdbdb',
+          4: '#a6a6a6',
+          5: '#9c9c9c',
+          6: '#737373',
+          7: '#595959',
+          8: '#3f3f3f',
+          9: '#202020'
+        },
+        slate: {
+          //0: '#f4f4f6', Proposed
+          1: '#e3e3e5',
+          3: '#babac4',
+          5: '#9c9cab',
+          7: '#595969' //9: '#131316', Proposed
+
+        },
         green: {
@@ -26,0 +36,0 @@ success: '#00a36d'

package.json

 {
   "name": "@hypothesis/frontend-shared",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "description": "Shared components, styles and utilities for Hypothesis projects",
@@ -43,3 +43,3 @@ "license": "BSD-2-Clause",
     "karma-source-map-support": "^1.4.0",
-    "mocha": "9.2.0",
+    "mocha": "9.2.2",
     "mustache": "^4.2.0",
@@ -46,0 +46,0 @@ "mustache-express": "^1.3.0",

README.md

@@ -19,2 +19,4 @@ # Shared resources for Hypothesis front-end applications
 
+Your project must have `sass` and `tailwindcss` dependencies installed.
+
 To add styles for all shared components to your project's SASS:
@@ -29,3 +31,3 @@
 ```js
-import { SvgIcon } from '@hypothesis/frontend-shared';
+import { Icon } from '@hypothesis/frontend-shared';
 ```
@@ -32,0 +34,0 @@

styles/README.md

 # SASS structure and conventions
 
-The public SASS interface for the `frontend-shared` package is:
+## Current API
 
-- `index.scss`:
+This package currently provides styles for all of its shared components as a single SASS entrypoint (`index.scss`) which is available to users of this package within their own SASS:
 
-  `@use '@hypothesis/frontend-shared/styles';`
+`@use '@hypothesis/frontend-shared/styles';`
 
-  All of the styles needed for the shared components provided by the package.
+## Conversion to Tailwind
 
-- `pattern-library.scss`:
+Hypothesis front-end applications are currently transitioning to a utility-first approach using [TailwindCSS](https://tailwindcss.com/docs/installation).
 
+To support consuming applications, this package provides a Tailwind preset (`src/tailwind.preset.js`) that represents our base design system. Applications may extend this preset in their own Tailwind configurations.
+
+This package's component styling is still implemented in SASS (with mixins, variables, etc.). The plan is to convert all of the styling in consuming applications to Tailwind before returning to this project and converting it as well.
+
+Until then, consuming applications may continue to use the main SASS entrypoint documented above.
+
+## Deprecated SASS API
+
+- `pattern-library.scss` (deprecated):
+
   `@use '@hypothesis/frontend-shared/styles/pattern-library';`
@@ -17,3 +27,3 @@
 
-- `mixins`:
+- `mixins` (deprecated):
 
@@ -26,91 +36,1 @@ `@use '@hypothesis/frontend-shared/styles/mixins/<mixin-module>';`
 _Note_: `pattern-library.scss` is also used internally by this project to build a CSS bundle for serving the pattern library using `make dev`.
-
-## Quick FAQ
-
-### Q: Should we be replacing utility variables, mixins and styles in consuming applications with these shared versions?
-
-**A**: Ultimately, yes, but _not yet_. As shared atomic patterns, base styling and utilities are migrated and centralized here, they are being tightened up and applied in a more refined state to the components that are provided by the package. They may conflict with existing utility classes and mixins in other applications in implementation and naming and **should not be used directly (yet)**.
-
-Utility mixins and classes are being added as-needed, and the current collection is incomplete.
-
-(See above about the current public interface for this package's SASS assets).
-
-### Q: But not all of the existing modules and directories follow the patterns given below—wat?
-
-**A**: This is very true! Please consider this document aspirational and evolving. For example, the modules and directories for the shared button components don't currently align with this structure. There is work to do.
-
-### Q: But wait, I need access to other SASS modules to get at mixins or to customize something.
-
-**A**: This is most salient for shared button components at present.
-
-Note that all SASS modules in this project's package can be imported, by deeper traversal, e.g. `@use '@hypothesis/frontend-shared/styles/components/buttons`, though this will be increasingly discouraged as this package matures.
-
-Isolate your customizations within a single module in the consuming application SASS (avoid adding dependencies to this repository's SASS in multiple places for ease of maintenance later). See the `client` for how buttons are customized in SASS. It is the hope that customization will become a rarer exception as these patterns get more established.
-
-## Directories
-
-The directory that a SASS module lives in dictates what it should provide (styles, mixins, variables, etc.) and what kind of dependencies it is allowed:
-
-| Directory    | Description                                                   | Provides             | Dependencies          |
-| ------------ | ------------------------------------------------------------- | -------------------- | --------------------- |
-| `base`       | Reset and element styles. Used only by the pattern library.   | styles               | mixins, variables[^1] |
-| `components` | Styles for shared components                                  | styles               | any                   |
-| `mixins`     | Mixins                                                        | mixins               | mixins[^2], variables |
-| `patterns`   | Pattern styles                                                | styles               | mixins                |
-| `util`       | Utility styles                                                | styles               | mixins                |
-| `variables`  | Variables and functions that return values based on variables | variables, functions | none                  |
-
-## CSS Output and Ordering
-
-The current SASS entry point for the package only generates styles from `components`.
-
-Other CSS output is currently private to the package, and used (only) by the pattern library.
-
-The intended ordering of CSS output—to assure proper cascade/ordering—is:
-
-1. `base`
-2. `components`
-3. `patterns`
-4. `utils`
-
-Note `utils` in last position, to assure these classes override other rules.
-
-## Conventions
-
-### Selectors and Class naming
-
-All class-name selectors generated by this package's SASS must be prefixed (see details below). We use [BEM (Block Element Modifier)](http://getbem.com/) methodology for class naming.
-
-_Note_: `base` modules use element selectors (no class names). These element selectors and resets are used by the pattern library internally and are not currently part of the public API.
-
-- Component class names should be prefixed with `.Hyp-` and use PascalCase, e.g. `.Hyp-SomePanel`.
-- All other class names should be kebab-case:
-  - Pattern (module, organism, etc.) class names should be prefixed with `.hyp-`, e.g. `.hyp-card`.
-  - Utility class names should be prefixed with `.hyp-u-`, e.g. `.hyp-u-border--left`. These are classes that may be used individually to adjust styling on a single element.
-
-### Variables
-
-- To help manage dependencies, it is a friendly touch to assign variables to local members[^3] near the top of modules that have variable dependencies, e.g.:
-
-  `$-color-border: var.$color-border;`
-
-  And then make use of `$-color-border` in the module. This helps make it easier to understand a member's scope when scanning longer modules and helps with dependency maintenance.
-
-- Module imports should be ordered "outward-in" and alphabetized, with SASS builtins, then third-party imports first, e.g.
-
-  ```sass
-  @use 'sass:map';
-
-  @use 'some-third-party-thing';
-
-  @use '../variables' as var;
-
-  @use 'a-local-partial';
-  @use 'b-local-partial';
-  ```
-
-  Modules that output styles may `@use` modules in the order needed for correct cascade, however.
-
-[^1]: Variable dependencies: sparingly. Ideally, not.
-[^2]: Mixin modules in top-level `mixins` directory should not depend on other `mixins`.
-[^3]: Members prefixed with `-` are considered "private" by SASS

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

817896

increased by0.08%

Lines of code

10445

increased by0.67%

Number of lines in readme file

37

increased by5.71%

No dependency changes