@seveelly/baseui 16.1.1

package/documentation-site/pages/blog/base-web-v9/metadata.json

@@ -0,0 +1,17 @@
+{
+  "author": "Graham Murdoch",
+  "authorLink": "https://github.com/sandgraham",
+  "title": "Color and Typography Updates in v9",
+  "tagline": "Everything you need to know about the latest style updates in Base Web",
+  "date": "9 September 2019",
+  "coverImage": "https://res.cloudinary.com/dawr8pobn/image/upload/v1565816562/baseblack_oodvc1.png",
+  "coverImageWidth": 1200,
+  "coverImageHeight": 630,
+  "keyWords": [
+    "Base Web",
+    "Design System",
+    "React",
+    "Migration Guide",
+    "Major Version"
+  ]
+}

package/documentation-site/pages/blog/drag-and-drop-list/index.mdx

@@ -0,0 +1,301 @@
+import metadata from "./metadata.json";
+import Layout from "../../../components/layout";
+import { BlogImage, Meta, Caption } from "../../../components/blog";
+import { TwitterTweetEmbed } from "react-twitter-embed";
+import Removable from "../../../examples/dnd-list/removable";
+
+export default Layout;
+
+<Meta data={metadata} />
+
+<BlogImage
+  src="https://res.cloudinary.com/flycatcher/image/upload/v1572289775/listgif_igl9j7.gif"
+  alt="Base Web DnD List component"
+  caption="Base Web DnD List component"
+/>
+
+The drag and drop interaction was invented in the 1970's by [Jef Raskin](https://en.wikipedia.org/wiki/Jef_Raskin) as a part of the Macintosh project. That's 40 years ago! So how come that making things draggable on the web is still so painful? We were recently looking for answers since our component library needs to support a sortable list and slider.
+
+## Our Sortable List Component
+
+<Removable />
+
+## HTML Drag and Drop API
+
+There is an official [HTML drag and drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API), it was introduced in the HTML5 standard and it comes with eight different events:
+
+- drag
+- dragend
+- dragenter
+- dragexit
+- dragleave
+- dragover
+- dragstart
+- drop
+
+Here is a little pop quiz for you. What's the difference between `dragexit` and `dragleave`? Not sure? It takes some imagination to implement eight different events for something that could be described by three user actions:
+
+- pressing the mouse button
+- moving the mouse
+- releasing the mouse button
+
+That is not the only strange thing about this API. Some other "glitches":
+
+- **no support for touch devices** (ugh)
+- limited styling options for dragged items
+- the API is wildly inconsistent across browsers
+
+You might wonder why this relatively new API is so bad. The answer might surprise you:
+
+<TwitterTweetEmbed tweetId={"4075253361"} />
+
+Yes, Internet Explorer 6 is the culprit here. If we don't want to settle with no mobile support and other shortcomings, what else we can do?
+
+(The dragexit event is fired when an element is no longer the drag operation's immediate selection target. The dragleave event is fired when a dragged element or text selection leaves a valid drop target.)
+
+## Tracking Basic Actions
+
+Fortunately, there are still good old mouse and touch events:
+
+- mousedown (touchstart)
+- mousemove (touchmove)
+- mouseup (touchend, touchcancel)
+
+They also nicely translate into our three drag and drop actions.
+
+## Mouse/Finger Coordinates
+
+Another information we need is the coordinates of the mouse/finger at any given point. That's very straightforward since all mouse/touch events pass them through. Mouse events:
+
+- `event.clientX`
+- `event.clientY`
+
+Touch events:
+
+- `event.touches[0].clientX`
+- `event.touches[0].clientY`
+
+## Measuring Elements
+
+We need to measure things. There is a great API with a horrible name. Let me introduce you [`Element.getBoundingClientRect`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). Call it on any element and it returns its dimensions and locations:
+
+```
+{
+  "width": 500,
+  "height": 100,
+  "top": 674,
+  "right": 800,
+  "bottom": 774,
+  "left": 1300
+}
+```
+
+## Positioning
+
+As user "moves" an item around, we need to keep changing its position to actually create the illusion of moving. The first naive solution could look like this:
+
+```css
+position: fixed;
+top: 100px;
+left: 200px;
+```
+
+As user moves the item, we apply position fixed and keep updating its top and left values. This works reasonably well. However, the better solution is using CSS transforms:
+
+```css
+transform: translate(10px, 20px);
+transition-duration: 1s;
+```
+
+It's GPU accelerated, requires less work from the browser and we can also combine it with transition-duration to animate it.
+
+## Other DOM APIs
+
+There are many other useful DOM APIs to deal with scrolling, container manipulation or optimizing the browser workload:
+
+```js
+window.getComputedStyle(ELement);
+window.scrollTo(X, Y);
+window.pageXOffset;
+window.pageYOffset;
+window.innerHeight;
+Element.contains();
+Element.scrollTop;
+requestAnimationFrame(() => {});
+```
+
+## ReactDOM.createPortal
+
+There is also one very useful React API - [Portals](https://reactjs.org/docs/portals.html).
+
+> Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+
+Why would we need such a thing? It's the only way to make the positioning of dragged items reliable.
+
+```jsx
+render() {
+  return ReactDOM.createPortal(
+    <li>Dragged</li>,
+    document.body
+  );
+}
+```
+
+In this example, we "portal" the dragged list item to the bottom of document body. This way the item has no parents and there are no inherited CSS properties that could impact its position (like CSS transforms). You can often see this technique being used for modals or notifications.
+
+## The Algorithm
+
+We have all the tools and APIs we need. Now it's time to put it all into a single algorithm.
+
+<BlogImage
+  src="https://res.cloudinary.com/flycatcher/image/upload/v1572409269/Screen_Shot_2019-10-29_at_9.20.29_PM_ye0moq.png"
+  style={{ width: "50%" }}
+  alt="User starts dragging the second item"
+  caption="user starts dragging the second item"
+/>
+
+User clicks on the second item and starts dragging it. We set its visibility to hidden so it preserves the current space occupied by the item and at the same time we portal it to the root. We give it an initial top and left position and as user keeps moving, we update the translate values.
+
+<BlogImage
+  src="https://res.cloudinary.com/flycatcher/image/upload/v1572409269/Screen_Shot_2019-10-29_at_9.20.33_PM_gsdj15.png"
+  style={{ width: "50%" }}
+  alt="User reaches the boundary of the third item"
+  caption="User reaches the boundary of the third item"
+/>
+
+The user reached the boundary of the third item so we want to move the third item to the second position. All we need to do is applying a negative translate Y value. We should also add the transition property to animate it.
+
+So far we didn't change the DOM order of our items. That happens only after the user finishes the drop.
+
+There are many ways how you could go about it but this algorithm is pretty straightforward and works.
+
+## Accessibility
+
+What does it mean? You should be able to control our component only through the keyboard and screen reader. There is a set of keyboard shortcuts we implement:
+
+- `tab` and `shift+tab` to focus a item
+- `space` to lift or drop the item
+- `j` or `arrow down` to move the lifted item down
+- `k` or `arrow up` to move the lifted item up
+- `escape` to cancel the lift and return the item to its initial position
+
+We also need to provide audible cues through the screen reader. First, we should [describe each item](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Application_Role) so it's clear that you can move it:
+
+```html
+<li aria-roledescription="This is a draggable item. Press space to lift.">
+  Item 1
+</li>
+```
+
+Then we provide additional messages as the user goes through the interaction:
+
+```html
+<div aria-live="assertive" role="log" aria-atomic="true">
+  You have lifted item at position 5. Press j to move it down...
+</div>
+```
+
+This is called [ARIA live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). Whatever you set its content to gets announced by the screen reader. Check [this article](https://medium.com/salesforce-ux/4-major-patterns-for-accessible-drag-and-drop-1d43f64ebf09) for more details.
+
+## Little Things
+
+There are some little things that you might now even notice but they make the whole interaction nicer. For example, the drop animation. There is none here:
+
+<BlogImage
+  src="https://res.cloudinary.com/flycatcher/image/upload/v1572410948/drop1_xpwz2d.gif"
+  style={{ width: "50%" }}
+  alt="No drop animation."
+  caption="No drop animation"
+/>
+
+On the other hand, we use
+
+```css
+transition: 0.3s cubic-bezier(0.2, 1, 0.1, 1);
+```
+
+bellow to make the item fly back which gives user a nice additional feedback:
+
+<BlogImage
+  src="https://res.cloudinary.com/flycatcher/image/upload/v1572410952/drop2_vamnka.gif"
+  style={{ width: "50%" }}
+  alt="The drop is animated."
+  caption="The drop is animated."
+/>
+
+And there are many other small interactions like this to consider.
+
+## Testing
+
+Any drag and drop library needs to rely on a multiple DOM APIs. If you want to write unit tests, you would have to mock out all of them. What are you even testing at that point? Focusing on end to end tests might be a better solution. With [Playwright](https://playwright.dev) you can write short and descriptive tests. Here we are testing the whole interaction using the mouse:
+
+```js
+test("dnd the first item to second position", async () => {
+  await page.mouse.move(190, 111);
+  await page.mouse.down();
+  await page.mouse.move(190, 190);
+  await page.mouse.up();
+  expect(await getListItems(page)).toEqual([
+    "Item 2",
+    "Item 1",
+    "Item 3",
+    "Item 4",
+    "Item 5",
+    "Item 6",
+  ]);
+});
+```
+
+We just move the mouse around and check the order of DOM elements at the end. The test for keyboard is similar:
+
+```js
+test("move the first item to second position", async () => {
+  await page.keyboard.press("Tab");
+  await page.keyboard.press("Space");
+  await page.keyboard.press("ArrowDown");
+  await page.keyboard.press("Space");
+  expect(await getListItems(page)).toEqual([
+    "Item 2",
+    "Item 1",
+    "Item 3",
+    "Item 4",
+    "Item 5",
+    "Item 6",
+  ]);
+});
+```
+
+## Gotchas
+
+There is a class of bugs that regular tests might not cover. Since we deal with a lot of positioning it's quite easy to misplace some items by a few pixels. We can utilize visual regression testing with [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot). It takes an image (snapshot) of our functioning component, takes another one on the subsequent run and compares them pixel by pixel. If there is any difference, the test fails. Be aware that each OS renders fonts differently. You might need to use docker to keep the tests reliable.
+
+### Internet Explorer
+
+Frankly, it would be surprising to open IE for the first time and see everything working. Fortunately, the issues are relatively minor:
+
+- `transform: translate` doesn't work for table rows
+- `window.scrollBy` doesn't exist
+- `window.scrollY` needs to be replaced by `window.pageYOffset`
+- `window.scroll` needs to be replaced `window.scrollTo`
+
+## Safari and Scrolling
+
+The gesture for touch scrolling and drag and drop is exactly the same, so we need to disable the touch scrolling. Luckily for us there is a CSS property just for that:
+
+```css
+touch-action: none;
+```
+
+and it works in all browsers. **Except Safari**. What do you do when CSS fails you? Use more JavaScript! We can `e.preventDefault` all touch events. However, don't forget to make your event listeners **not passive**:
+
+```js
+document.addEventListener("touchstart", _, { passive: false });
+```
+
+since otherwise the `e.preventDefault()` calls are ignored by default. This also means you can't use React event system at all - use native events only.
+
+## Conclusion
+
+Building a drag and drop web experience is involved but not impossible. **You should never compromise on mobile support and accessibility**. To ensure that, avoid the HTML5 API and go with mouse/touch events. For positioning, CSS transforms are the right choice. Browsers provide many great APIs like getBoundingClientRect for measuring things. And before you release anything, don't forget to write tests. Playwright makes it easy!
+
+I gave a talk about this topic at [React Advanced London 2019](https://www.youtube.com/watch?v=q6TD3PvmQts&feature=youtu.be&t=6770). We published a separate open-source library [react-movable](https://github.com/tajo/react-movable). The Base DnD List uses it internally.

package/documentation-site/pages/blog/drag-and-drop-list/metadata.json

@@ -0,0 +1,11 @@
+{
+  "author": "Vojtech Miksu",
+  "authorLink": "https://twitter.com/vmiksu",
+  "title": "Building a Drag and Drop List",
+  "tagline": "What goes into building a drag and drop component in 2019?",
+  "date": "30 October 2019",
+  "coverImage": "https://res.cloudinary.com/flycatcher/image/upload/v1572289775/listgif_igl9j7.gif",
+  "coverImageWidth": 600,
+  "coverImageHeight": 383,
+  "keyWords": ["Drag and Drop", "React", "DnD"]
+}

package/documentation-site/pages/blog/file-uploader/index.mdx

@@ -0,0 +1,202 @@
+import Layout from "../../../components/layout";
+import { BlogImage, Meta, Caption } from "../../../components/blog";
+import { Block } from "baseui/block";
+import { StatefulInput } from "baseui/input";
+import { StatefulSelect } from "baseui/select";
+import { StatefulPaymentCard } from "baseui/payment-card";
+import { StatefulPhoneInput } from "baseui/phone-input";
+import { FileUploader } from "baseui/file-uploader";
+import architectureDiagram from "../../../public/images/blog/file-uploader/file-uploader-architecture-diagram.png";
+import carouselView from "../../../public/images/blog/file-uploader/carousel-view.png";
+import gridView from "../../../public/images/blog/file-uploader/grid-view.png";
+import listView from "../../../public/images/blog/file-uploader/list-view.png";
+import metadata from "./metadata.json";
+
+export default Layout;
+
+<Meta data={metadata} />
+
+In August 2024, we introduced a new [File Uploader](/components/file-uploader) component to Base Web.
+
+<FileUploader />
+<Caption>The new File Uploader component</Caption>
+
+## Background
+
+In December 2018, the baseweb team implemented the basic [File Uploader](/components/file-uploader) component.
+However, this component lacks [statefulness](https://github.com/uber/baseweb/pull/795).
+Demand at Uber has grown for an advanced component that can handle complex use cases.
+Several teams implemented custom file uploader components, leading to UI/UX inconsistencies.
+Additionally, new product requests required stateful file upload handling on Uber's [Insurance Tech](https://www.uber.com/blog/insuretech-insurance-compliance/) team.
+
+This was an opportunity to provide an immediate impact on the insurance team, save engineering time across Uber, and improve UI/UX consistency.
+
+## Goals
+
+1. Maintain an internal state across file uploads each time the user selects "Browse files"
+
+```js
+import type { FileRow } from 'baseui/file-uploader';
+
+const [fileRows, setFileRows] = React.useState<Array<FileRow>>([]);
+```
+
+2. Provide a UI for each uploaded file including the filename, file size in a human-readable format, and one of three states: 1. Success 2. Error (e.g. invalid file type, file too large, etc.) 3. Loading
+   <FileUploader
+     fileRows={[
+       {
+         file: new File(["test file 1"], "success.jpeg"),
+         id: "0",
+         status: "processed",
+         errorMessage: null,
+       },
+       {
+         file: new File(["test file 2"], "error.jpeg"),
+         id: "1",
+         status: "error",
+         errorMessage: "file type of img/jpeg is not accepted",
+       },
+       {
+         file: new File(["test file 3"], "loading.jpeg"),
+         id: "2",
+         status: "added",
+         errorMessage: null,
+       },
+     ]}
+   />
+3. Provide a delete operation that removes files from the internal state, represented by a trash can icon
+   <FileUploader
+     fileRows={[
+       {
+         file: new File(["test file 1"], "success.jpeg"),
+         id: "0",
+         status: "processed",
+         errorMessage: null,
+       },
+     ]}
+   />
+
+## Design considerations
+
+### Architecture
+
+<BlogImage src={architectureDiagram} />
+
+A `processFileOnDrop` function is passed as a prop.
+It is executed on each file upload.
+It is extensible, allowing applications to run synchronous or asynchronous code.
+
+### Dropzone
+
+The file uploader leverages the [react-dropzone](https://react-dropzone.js.org/) package under the hood to handle file drops directly.
+Serious considerations were made to upgrade this package to the latest version.
+The largest improvement would be including a new `validator` prop.
+This prop runs before the `onDrop` callback, sorting files into two buckets: `acceptedFiles` and `rejectedFiles`.
+Application code could pass a custom validation function to show errors while keeping the `onDrop` callback for file processing.
+
+However, there were significant drawbacks to this approach.
+Most notable, the `validator` prop [runs synchronously](https://github.com/react-dropzone/react-dropzone/blob/99b43e802e42f949b9c19aaf74556d611584353d/src/index.js#L582).
+Asynchronous errors due to API upload errors or server-side security checks would not be caught.
+Applications could modify file state in the `onDrop` callback as a workaround, but this violates [separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns).
+Application code **AND** library code would be responsible for file state management.
+
+### Server-side support
+
+Instead of demanding applications to pass a `processFileOnDrop` function prop, another consideration was implementing server-side handling within the component.
+Plenty of third-party options exist such as [filepond](https://pqina.nl/filepond/) and [uppy](https://uppy.io/).
+Each of these libraries has pros and cons. Both provide out-of-the-box support for server-side handling.
+However, introducing server-side handling comes with notable drawbacks:
+
+1. Reduced flexibility for applications to handle server-side integrations.
+2. Potential security risks. Applications have to trust the third-party library to handle file uploads securely.
+3. Each component in the Base Web library lives entirely on browser-rendered code. Introducing reusable server code would be a significant deviation from the current paradigm.
+
+## Feature improvements
+
+### Statefulness
+
+As mentioned in the Goals section, the new File Uploader component is stateful.
+It leverages the `useState` hook to maintain an internal state across file uploads.
+
+```js
+import React from 'react';
+import { type FileRow, FileUploader } from 'baseui/file-uploader';
+
+const myApplicationComponent = () => {
+  const [fileRows, setFileRows] = React.useState<Array<FileRow>>([]);
+
+  return <FileUploader fileRows={fileRows} setFileRows={setFileRows} />
+}
+```
+
+### Error handling
+
+Some browser-side errors are handled out of the box using the [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) API.
+They can be leveraged with the `accept`, `minSize`, `maxSize`, and `maxFiles` props.
+Applications can use these props for browser-side error handling and `processFileOnDrop` for server-side error handling.
+
+<FileUploader
+  fileRows={[
+    {
+      file: new File(["test file 1"], "unaccepted-file-type.jpeg"),
+      id: "0",
+      status: "error",
+      errorMessage: "file type of img/jpeg is not accepted",
+    },
+    {
+      file: new File(["test file 2"], "file-too-small.png"),
+      id: "1",
+      status: "error",
+      errorMessage: "file size must be greater than 20 KB",
+    },
+    {
+      file: new File(["test file 3"], "file-too-big.png"),
+      id: "2",
+      status: "error",
+      errorMessage: "file size must be less than 100 KB",
+    },
+    {
+      file: new File(["test file 4"], "file-count-too-many.png"),
+      id: "3",
+      status: "error",
+      errorMessage: "cannot process more than 3 file(s)",
+    },
+  ]}
+/>
+
+### Future considerations
+
+Size adjustments and additional layouts were considered for the file uploader component.
+The component can extend to support these use cases in future iterations.
+These include:
+
+#### List view
+
+<BlogImage
+  caption={"Implemented in the initial release with the itemPreview prop"}
+  src={listView}
+/>
+
+#### Grid view
+
+<BlogImage caption={"Not included in the initial release"} src={gridView} />
+
+#### Carousel view
+
+<BlogImage caption={"Not included in the initial release"} src={carouselView} />
+
+## Conclusion
+
+### Key learnings
+
+There are many takeaways from working on this project. The learnings include but are not limited to:
+
+- When faced with a new problem, ask yourself: **"Has this already been solved?"**. If the answer is yes, consider leveraging existing solutions and look to extend them. If the answer is no, take some time to ask around if other teams have faced similar problems. You can multiply your impact by building in public instead of solving the problem in a silo.
+- **Listen for existing problems at your company.** The tech world moves rapidly and stakeholder deadlines can apply time constraints to your work. This pressure makes it easy to stay in your domain of expertise without noticing if other teams have overlapping problems. So how do you notice duplicative solutions? Keep a list of problems you notice in your codebase, team, and organization. Additions to the list should take one or two minutes of your time. Over time you will naturally notice overlapping problems. When a stakeholder asks you to solve a new one and it is already on your list, you suddenly have an opportunity for multiplicative impact!
+- **Just because you notice one solution for two similar problems does not mean it will take half the work.** Complexity grows when the solution space is expanded; prepare to spend more time than you initially thought. For the file uploader, more time was spent on refined UI/UX designs, accessibility requirements, alternative library research, and generating buy-in from the platform team. The good news is that the workload does not scale linearly with the problem space, but it is not as simple as implementing it in a vacuum on the tech stack you are accustomed to.
+
+### Summary
+
+The new File Uploader component is stateful, extensible, and provides a consistent user experience.
+Application developers can quickly implement file upload functionality by building out file row state binding, props to control errors, and props to control uploads.
+Stay tuned for future updates to the Base Web library.

package/documentation-site/pages/blog/file-uploader/metadata.json

@@ -0,0 +1,11 @@
+{
+  "author": "Emerson Pfeiffer",
+  "authorLink": "https://github.com/epfeiffe",
+  "title": "Introducing the File Uploader Component",
+  "tagline": "Adding state to a reusable file uploader component",
+  "date": "15 August 2024",
+  "coverImage": "/images/blog/file-uploader/file-uploader.gif",
+  "coverImageWidth": 960,
+  "coverImageHeight": 575,
+  "keyWords": ["Base Web", "File Upload", "React", "react-dropzone"]
+}