@khanacademy/wonder-blocks-filters 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @khanacademy/wonder-blocks-filters
+
+## 0.1.0
+
+### Minor Changes
+
+- b0dfff3: Add `ExclusiveCategoryFilter`, a radio group for filtering a list by one category at a time. It has a required visible label, one tab stop, and arrow-key navigation that moves focus and selection together
+- 8fc8e0a: ExclusiveCategoryFilter: Add visual styles from the Figma spec and the `startIcon` option property
+- 16ddb19: Add new `@khanacademy/wonder-blocks-filters` package
+
+### Patch Changes
+
+- b0dfff3: ExclusiveCategoryFilter: Sync the parent when the first option is chosen while `selectedValue` matches no option, use index-based option ids, follow the nearest `dir` for arrow keys, and render the label with `BodyText`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Khan Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/components/__tests__/exclusive-category-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/exclusive-category-filter.d.ts

@@ -0,0 +1,101 @@
+import * as React from "react";
+import { StyleType } from "@khanacademy/wonder-blocks-core";
+export type ExclusiveCategoryFilterOption = {
+    /**
+     * A unique value for the option. It is passed to `onChange` when the
+     * option is selected.
+     */
+    value: string;
+    /**
+     * The visible label for the option. It is also the option's accessible
+     * name.
+     */
+    label: string;
+    /**
+     * Optional icon shown before the label: a `PhosphorIcon` or `Icon`
+     * element, rendered as passed with the small size as the default.
+     *
+     * The icon is decorative unless it has an `aria-label`. Give it one when
+     * the icon adds meaning the label doesn't; it then becomes part of the
+     * option's accessible name.
+     */
+    startIcon?: React.ReactElement;
+    /**
+     * Optional id for the option. If not set, the option uses
+     * `${id}-option-${index}`.
+     */
+    id?: string;
+    /**
+     * Optional test ID for e2e testing. If not set, the option uses
+     * `${testId}-${value}` when the component has a `testId`.
+     */
+    testId?: string;
+};
+type Props = {
+    /**
+     * A unique id to use as the base of the ids for the elements within the
+     * component. If the `id` prop is not provided, a base unique id will be
+     * auto-generated.
+     *
+     * Here is how the id is used for the different elements in the component:
+     * - The root will have an id of `${id}`
+     * - The label will have an id formatted as `${id}-label`
+     * - Each option will have an id formatted as `${id}-option-${index}`,
+     *   unless the option sets its own `id`.
+     */
+    id?: string;
+    /**
+     * Optional test ID for e2e testing. Here is how the test id is used for
+     * the different elements in the component:
+     * - The root will have a testId formatted as `${testId}`
+     * - Each option will have a testId formatted as `${testId}-${value}`,
+     *   unless the option sets its own `testId`.
+     */
+    testId?: string;
+    /**
+     * The visible label for the group of options (e.g. "Filter by subject").
+     * It is also used as the accessible name of the radio group.
+     */
+    label: string;
+    /**
+     * The options to render, in order.
+     */
+    options: ReadonlyArray<ExclusiveCategoryFilterOption>;
+    /**
+     * The value of the selected option. Exactly one option is always
+     * selected.
+     *
+     * If it doesn't match any option, the first option is selected by
+     * default. `onChange` is not called until the user chooses an option.
+     */
+    selectedValue: string;
+    /**
+     * Called with the value of the newly selected option. It is not called
+     * when the selected option is clicked again, since the selection can't
+     * be cleared.
+     */
+    onChange: (value: string) => unknown;
+    /**
+     * Custom styles for the `ExclusiveCategoryFilter` component.
+     * - `root`: Styles the root element.
+     * - `label`: Styles the label element.
+     * - `options`: Styles the element that contains the options.
+     * - `option`: Styles all the option elements.
+     */
+    styles?: {
+        root?: StyleType;
+        label?: StyleType;
+        options?: StyleType;
+        option?: StyleType;
+    };
+};
+/**
+ * A group of options for filtering a list by one category at a time. Exactly
+ * one option is always selected.
+ *
+ * The component follows the ARIA APG Radio Group pattern: the options are
+ * radio buttons with a single tab stop, and the arrow keys move focus to the
+ * next or previous option and select it.
+ */
+export declare const ExclusiveCategoryFilter: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/es/index.js

@@ -0,0 +1,11 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import * as React from 'react';
+import { StyleSheet } from 'aphrodite';
+import { addStyle, keys, View } from '@khanacademy/wonder-blocks-core';
+import { focusStyles } from '@khanacademy/wonder-blocks-styles';
+import { sizing, border, semanticColor } from '@khanacademy/wonder-blocks-tokens';
+import { BodyText, styles as styles$1 } from '@khanacademy/wonder-blocks-typography';
+
+const StyledButton=addStyle("button");function renderStartIcon(startIcon){return React.cloneElement(startIcon,{size:startIcon.props.size??"small"})}const ExclusiveCategoryFilter=React.forwardRef(function ExclusiveCategoryFilter(props,ref){const{id,testId,label,options,selectedValue,onChange,styles:stylesProp}=props;const generatedUniqueId=React.useId();const uniqueId=id??generatedUniqueId;const labelId=`${uniqueId}-label`;const optionRefs=React.useRef({});const matchingIndex=options.findIndex(option=>option.value===selectedValue);const selectedIndex=matchingIndex===-1?0:matchingIndex;const selectOption=React.useCallback(value=>{optionRefs.current[value]?.focus();if(value!==selectedValue){onChange(value);}},[onChange,selectedValue]);const handleKeyDown=React.useCallback(event=>{const currentIndex=options.findIndex(option=>option.value===event.currentTarget.value);const isRtl=event.currentTarget.closest("[dir]")?.getAttribute("dir")==="rtl";let nextIndex;switch(event.key){case keys.up:case isRtl&&keys.right:case!isRtl&&keys.left:{nextIndex=(currentIndex-1+options.length)%options.length;break}case keys.down:case isRtl&&keys.left:case!isRtl&&keys.right:{nextIndex=(currentIndex+1)%options.length;break}default:{return}}event.preventDefault();selectOption(options[nextIndex].value);},[options,selectOption]);if(options.length===0){return jsx(React.Fragment,{})}return jsxs(View,{ref:ref,id:uniqueId,testId:testId,style:[styles.root,stylesProp?.root],children:[jsx(BodyText,{tag:"span",weight:"semi",id:labelId,style:[styles.label,stylesProp?.label],children:label}),jsx(View,{role:"radiogroup","aria-labelledby":labelId,style:[styles.options,stylesProp?.options],children:options.map((option,index)=>{const checked=index===selectedIndex;const optionTestId=option.testId??(testId?`${testId}-${option.value}`:undefined);return jsxs(StyledButton,{ref:element=>{optionRefs.current[option.value]=element;},id:option.id??`${uniqueId}-option-${index}`,"data-testid":optionTestId,type:"button",role:"radio","aria-checked":checked,tabIndex:checked?0:-1,value:option.value,onClick:()=>selectOption(option.value),onKeyDown:handleKeyDown,style:[styles$1.BodyTextMediumSemiWeight,styles.option,checked&&styles.selected,stylesProp?.option],children:[option.startIcon&&renderStartIcon(option.startIcon),option.label]},option.value)})})]})});const mediumBorderPaddingInline=`calc(${sizing.size_160} - (${border.width.medium} - ${border.width.thin}))`;const styles=StyleSheet.create({root:{gap:sizing.size_080},label:{color:semanticColor.core.foreground.neutral.default,overflowWrap:"anywhere"},options:{flexDirection:"row",flexWrap:"wrap",gap:sizing.size_080},option:{display:"inline-flex",alignItems:"center",gap:sizing.size_080,boxSizing:"border-box",overflowWrap:"anywhere",minBlockSize:sizing.size_400,maxInlineSize:"100%",margin:0,paddingBlock:sizing.size_080,paddingInline:sizing.size_160,textAlign:"start",cursor:"pointer",color:semanticColor.core.foreground.neutral.subtle,backgroundColor:semanticColor.core.transparent,border:`${border.width.thin} solid ${semanticColor.core.border.neutral.subtle}`,borderRadius:border.radius.radius_240,...focusStyles.focus,[":hover:not([aria-checked='true'])"]:{borderColor:semanticColor.core.border.neutral.default},[":active:not([aria-checked='true'])"]:{borderWidth:border.width.medium,borderColor:semanticColor.core.border.neutral.default,paddingInline:mediumBorderPaddingInline}},selected:{color:semanticColor.core.foreground.instructive.default,backgroundColor:semanticColor.core.background.instructive.subtle,borderWidth:border.width.medium,borderColor:semanticColor.core.border.instructive.default,paddingInline:mediumBorderPaddingInline}});
+
+export { ExclusiveCategoryFilter };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ExclusiveCategoryFilter } from "./components/exclusive-category-filter";
+export type { ExclusiveCategoryFilterOption } from "./components/exclusive-category-filter";

package/dist/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var jsxRuntime = require('react/jsx-runtime');
+var React = require('react');
+var aphrodite = require('aphrodite');
+var wonderBlocksCore = require('@khanacademy/wonder-blocks-core');
+var wonderBlocksStyles = require('@khanacademy/wonder-blocks-styles');
+var wonderBlocksTokens = require('@khanacademy/wonder-blocks-tokens');
+var wonderBlocksTypography = require('@khanacademy/wonder-blocks-typography');
+
+function _interopNamespace(e) {
+    if (e && e.__esModule) return e;
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n["default"] = e;
+    return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
+const StyledButton=wonderBlocksCore.addStyle("button");function renderStartIcon(startIcon){return React__namespace.cloneElement(startIcon,{size:startIcon.props.size??"small"})}const ExclusiveCategoryFilter=React__namespace.forwardRef(function ExclusiveCategoryFilter(props,ref){const{id,testId,label,options,selectedValue,onChange,styles:stylesProp}=props;const generatedUniqueId=React__namespace.useId();const uniqueId=id??generatedUniqueId;const labelId=`${uniqueId}-label`;const optionRefs=React__namespace.useRef({});const matchingIndex=options.findIndex(option=>option.value===selectedValue);const selectedIndex=matchingIndex===-1?0:matchingIndex;const selectOption=React__namespace.useCallback(value=>{optionRefs.current[value]?.focus();if(value!==selectedValue){onChange(value);}},[onChange,selectedValue]);const handleKeyDown=React__namespace.useCallback(event=>{const currentIndex=options.findIndex(option=>option.value===event.currentTarget.value);const isRtl=event.currentTarget.closest("[dir]")?.getAttribute("dir")==="rtl";let nextIndex;switch(event.key){case wonderBlocksCore.keys.up:case isRtl&&wonderBlocksCore.keys.right:case!isRtl&&wonderBlocksCore.keys.left:{nextIndex=(currentIndex-1+options.length)%options.length;break}case wonderBlocksCore.keys.down:case isRtl&&wonderBlocksCore.keys.left:case!isRtl&&wonderBlocksCore.keys.right:{nextIndex=(currentIndex+1)%options.length;break}default:{return}}event.preventDefault();selectOption(options[nextIndex].value);},[options,selectOption]);if(options.length===0){return jsxRuntime.jsx(React__namespace.Fragment,{})}return jsxRuntime.jsxs(wonderBlocksCore.View,{ref:ref,id:uniqueId,testId:testId,style:[styles.root,stylesProp?.root],children:[jsxRuntime.jsx(wonderBlocksTypography.BodyText,{tag:"span",weight:"semi",id:labelId,style:[styles.label,stylesProp?.label],children:label}),jsxRuntime.jsx(wonderBlocksCore.View,{role:"radiogroup","aria-labelledby":labelId,style:[styles.options,stylesProp?.options],children:options.map((option,index)=>{const checked=index===selectedIndex;const optionTestId=option.testId??(testId?`${testId}-${option.value}`:undefined);return jsxRuntime.jsxs(StyledButton,{ref:element=>{optionRefs.current[option.value]=element;},id:option.id??`${uniqueId}-option-${index}`,"data-testid":optionTestId,type:"button",role:"radio","aria-checked":checked,tabIndex:checked?0:-1,value:option.value,onClick:()=>selectOption(option.value),onKeyDown:handleKeyDown,style:[wonderBlocksTypography.styles.BodyTextMediumSemiWeight,styles.option,checked&&styles.selected,stylesProp?.option],children:[option.startIcon&&renderStartIcon(option.startIcon),option.label]},option.value)})})]})});const mediumBorderPaddingInline=`calc(${wonderBlocksTokens.sizing.size_160} - (${wonderBlocksTokens.border.width.medium} - ${wonderBlocksTokens.border.width.thin}))`;const styles=aphrodite.StyleSheet.create({root:{gap:wonderBlocksTokens.sizing.size_080},label:{color:wonderBlocksTokens.semanticColor.core.foreground.neutral.default,overflowWrap:"anywhere"},options:{flexDirection:"row",flexWrap:"wrap",gap:wonderBlocksTokens.sizing.size_080},option:{display:"inline-flex",alignItems:"center",gap:wonderBlocksTokens.sizing.size_080,boxSizing:"border-box",overflowWrap:"anywhere",minBlockSize:wonderBlocksTokens.sizing.size_400,maxInlineSize:"100%",margin:0,paddingBlock:wonderBlocksTokens.sizing.size_080,paddingInline:wonderBlocksTokens.sizing.size_160,textAlign:"start",cursor:"pointer",color:wonderBlocksTokens.semanticColor.core.foreground.neutral.subtle,backgroundColor:wonderBlocksTokens.semanticColor.core.transparent,border:`${wonderBlocksTokens.border.width.thin} solid ${wonderBlocksTokens.semanticColor.core.border.neutral.subtle}`,borderRadius:wonderBlocksTokens.border.radius.radius_240,...wonderBlocksStyles.focusStyles.focus,[":hover:not([aria-checked='true'])"]:{borderColor:wonderBlocksTokens.semanticColor.core.border.neutral.default},[":active:not([aria-checked='true'])"]:{borderWidth:wonderBlocksTokens.border.width.medium,borderColor:wonderBlocksTokens.semanticColor.core.border.neutral.default,paddingInline:mediumBorderPaddingInline}},selected:{color:wonderBlocksTokens.semanticColor.core.foreground.instructive.default,backgroundColor:wonderBlocksTokens.semanticColor.core.background.instructive.subtle,borderWidth:wonderBlocksTokens.border.width.medium,borderColor:wonderBlocksTokens.semanticColor.core.border.instructive.default,paddingInline:mediumBorderPaddingInline}});
+
+exports.ExclusiveCategoryFilter = ExclusiveCategoryFilter;

package/package.json

@@ -1,19 +1,38 @@
 {
   "name": "@khanacademy/wonder-blocks-filters",
-  "description": "Placeholder to allow Trusted Publishing configuration",
+  "description": "Filters are used to narrow the items shown in a list",
   "author": "Khan Academy",
   "license": "MIT",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
+  "design": "v1",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Khan/wonder-blocks.git"
+    "url": "https://github.com/Khan/wonder-blocks.git",
+    "directory": "packages/wonder-blocks-filters"
   },
   "bugs": {
     "url": "https://github.com/Khan/wonder-blocks/issues"
   },
-  "module": "index.js",
-  "main": "index.js"
+  "main": "dist/index.js",
+  "module": "dist/es/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@khanacademy/wonder-blocks-core": "12.5.0",
+    "@khanacademy/wonder-blocks-styles": "0.4.1",
+    "@khanacademy/wonder-blocks-typography": "5.0.6",
+    "@khanacademy/wonder-blocks-tokens": "18.1.0"
+  },
+  "peerDependencies": {
+    "aphrodite": "^1.2.5",
+    "react": "18.2.0"
+  },
+  "devDependencies": {
+    "@khanacademy/wb-dev-build-settings": "3.3.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
 }