Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jpdevries/eureka
HTML-first crack at a Flexible Media Browser progressively enhanced with React
https://github.com/jpdevries/eureka
accessibility browse contrast-theme html media modmore modx nodejs progressive-enhancement progressive-web-app react redux rest
Last synced: 2 days ago
JSON representation
HTML-first crack at a Flexible Media Browser progressively enhanced with React
- Host: GitHub
- URL: https://github.com/jpdevries/eureka
- Owner: jpdevries
- License: other
- Created: 2015-03-28T03:42:05.000Z (over 9 years ago)
- Default Branch: release-2.0
- Last Pushed: 2017-08-14T21:13:41.000Z (about 7 years ago)
- Last Synced: 2024-04-30T06:21:11.862Z (6 months ago)
- Topics: accessibility, browse, contrast-theme, html, media, modmore, modx, nodejs, progressive-enhancement, progressive-web-app, react, redux, rest
- Language: HTML
- Homepage: https://eureka.markup.tips/
- Size: 27.5 MB
- Stars: 18
- Watchers: 4
- Forks: 5
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Eureka 🌲
[](https://travis-ci.org/jpdevries/eureka) [](https://badge.fury.io/js/eureka-browser)
Eureka is a progressively enhanced flexible media browser. Connected to your media sources through a REST API, this accessible web component allows users to browse media sources, upload files, and choose media items.
[🤗 Try the demo](https://eureka.markup.tips/).
> With `eureka.js` users will be saying "I found it!" in no time.
— [@mrktps](https://twitter.com/mrktps)
## 💬 Discuss
Join the conversation in our public Gitter chat room.
[](https://gitter.im/jpdevries/eureka?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## 📚 Wiki
Don't forget to [browse the Wiki](https://github.com/jpdevries/eureka/wiki) for [more information on the REST API](https://github.com/jpdevries/eureka/wiki/REST-API), [patterns](https://github.com/jpdevries/eureka/wiki/Patterns), [screenshots](https://github.com/jpdevries/eureka/wiki/Screenshots) and more.
## 🍻 Support
The Eureka Media Browser and supporting resources are provided free as in beer.
[Gratuities are accepted through Square Cash](https://cash.me/$devriesdev).
## 🏋️♀️ Weigh In
The Eureka Media Browser is pretty lightweight all things considered.
| Asset | Weight (GZIP minified)
| ------------- |:-------------:|
| CSS Stylesheet | `7.83kB` |
| SVG Icons | `7.88kB` |
| React Component | `75.83kB` |
[Have a gander at our Webpack Visualizer](https://eureka.markup.tips/assets/js/stats.html) 👀 .
### 📄 HTML–first
As a progressively enhanced web component, Eureka is functional HTML–first. This means that technically anything other than the initial HTML layer is a non–critical enhancement. Critical features supported by the HTML layer, such as browse, upload, and choose, are universally supported and do not depend on modern browsers, CSS styles, or script.
😲 Take a gander at Eureka in the nued by waking our incredibly lightweight [raw HTML example](https://reacteureka.herokuapp.com/nued).
We also encourage you to temporarily disable JavaScript in your browser and party with Eureka like it's 1999.
## Powered By 🚀
- Progressively Enhanced from HTML components
- All–new Virtual DOM powered by React/Redux
- Node Server Side Rendering
- Node testing server
## Highlights 🖋
- Configurable Rest API endpoints
- Browse multiple media sources for images
- Drag and Drop Upload Support
- Flexible Layout
- Responsive Design
- Save Data with responsive thumbnails
- Configurable Styles via CSS Variables
- Accessible
- supports mobile and touch devices
- supports `.no-js` via server side rendering
- ARIA & Keyboard Support
- high contrast themes
## 🚥 Features
The level of isomorphism between the client and server side one can achieve with Node is unmatched. Eureka takes advantage of this unique strength of Node by, through an isomorphic server and standard synchronous forms, achieving full support for critical features.
No features rely solely on sight or the use of a mouse. Keyboard use is supported. Accommodations are taken for users that benefit from high contrast themes. Visually hidden text is used to convey aspects of the interface that are otherwise visually implied to screen readers and assistive technology.
The semantic HTML layer remains usable even absent of style as pure HTML.
Support of features against browser environments
Feature
.no-js
< IE 9
Chrome
Safari
Firefox
IE 11
Edge
Upload multiple files
✅
✅
✅
✅
✅
✅
✅
Browse directories
✅
✅
✅
✅
✅
✅
✅
Choose a media item
✅
✅
✅
✅
✅
✅
✅
Keyboard Support
✅
✅
✅
✅
✅
✅
✅
ARIA Support
✅
✳️
✅
✅
✅
✅
✅
WCAG Level AA
✅
✅
✅
✅
✅
✅
✅
Internationalization
✅
✅
✅
✅
✅
✅
✅
Download Item
✅
✅
✅
✅
✅
✅
✅
Choose Multiple Items
❌
❌
✅
✅
✅
✅
✅
Delete Multiple Items
❌
❌
✅
✅
✅
✅
✅
Keyboard Shortcuts
❌
❌
✅
✅
✅
✅
✅
Crop Images
❌
❌
✅
✅
✅
✅
✅
Paste to Upload
❌
❌
✅
✅
✅
✅
✅
Media Source panel
❌
❌
✅
✅
✅
✅
✅
Async UX
❌
❌
✅
✅
✅
✅
✅
Filterable Data Table
❌
❌
✅
✅
✅
✅
✅
Sortable Data Table
❌
❌
✅
✅
✅
✅
✅
Drag 'n drop uploads
❌
❌
✅
✅
✅
✅
✅
Grid Layout
✅
❌
✅
✅
✅
❌
❌
Flexible Layout
✅
❌
✅
✅
✅
✅
✅
View Chooser
❌
❌
✅
✅
✅
✅
✅
Masonry Layout Mode
❌
❌
✅
✅
✅
✅
✅
Pathbar
❌
❌
✅
✅
✅
✅
✅
Rename Item
❌
❌
✅
✅
✅
✅
✅
Delete Item
❌
❌
✅
✅
✅
✅
✅
Download Multiple Items
❌
❌
✅
✅
✅
✅
✅
Local Storage
❌
❌
✅
✅
✅
✅
✅
Variable Styles
✅
❌
✅
✅
✅
❌
✅
Accessible Themes
✅
❌
✅
✅
✅
❌
✅
Mobile First Layout
✅
✳️
✅
✅
✅
✅
✅
Fullscreen Mode
❌
❌
✅
✅
✅
✅
✅
HTML5 Context Menus
❌
❌
🔧
❌
✅
❌
❌
HTML5 Details
✳️
❌
✅
✅
✅
✳️
✅
HTML5 Datalist
✳️
❌
✅
❌
✅
✳️
✳️
## 🛠 Usage
```bash
npm install eureka-browser --save
```
#### Bower
You can also install Eureka via Bower, which is a good way to fetch its stylesheet and icon sprite. There is also a UMD export of the `EurekaMediaBrowser` component for the unlikely case you'll need it.
```bash
npm install -g bower
```
```bash
bower install eureka-browser#release-2.0
ls bower_components/eureka-browser/client/build/assets/css/ # default eureka theme
ls bower_components/eureka-browser/client/build/assets/img # icon sprite
ls bower_components/eureka-browser/client/build/assets/js # bundled and unbundled UMD exports of EurekaMediaBrowser component
```
#### HTML
The `` React component is styled by a standard CSS stylesheet. Include the CSS for the appropriate version of the media browser. Reference the theming section for [more information on styling Eureka](https://github.com/jpdevries/eureka#-theming).
```html
```
```html
```
#### JS
```js
import React from 'react';
import ReactDOM from 'react-dom';
import { EurekaMediaBrowser } from 'eureka-browser';
ReactDOM.render(
,
document.getElementById('eureka-root')
);
```
Eureka will then be injected into the DOM and eagerly reach out to the REST API for the JSON data it needs to offer the interface.
Configure the `EurekaMediaBrowser` via the optional attributes found in the default configuration below:
```xml
```
## ⚙️ Options
| Option | Default | Description |
| ------------- |:-------------:| -----|
| `basePath` | `"/"` | Prepended to URLs for XHR requests to the Rest API.
Set to the absolute path of your Rest API. |
| `allowUploads` | `true` | Whether or not to allow uploading of media items |
| `treeHidden` | `true` | Whether or not the Media Source Panel "sidebar" should be initially closed |
| `useLocalStorage` | `true` | Whether or not to use the JavaScript `localStorage` API to remember session data such as the last visited directory and view mode preference |
| `storagePrefix` | `"eureka__"` | Prepended to `localStorage` keys |
| `allowRename` | `true` | Whether or not to offer users the ability to rename directories and media items |
| `allowDelete` | `true` | Whether or not to offer users the ability to delete directories and media items |
| `allowDownload` | `false` | Whether or not to add a download button to media items |
| `confirmBeforeDelete` | `false` | Whether or not to confirm intent before users delete directories and media items |
| `locale` | `"en-US"` | The localization to use. See Lexicons. |
| `mediaSource` | `undefined` | The default initial media source id to use |
| `currentDirectory` | `"/"` | The default initial directory to use |
| `uid` | `"0"` | A unique identifier used to ensure multiple `` components on the same page do not share the same DOM ids |
| `assetsBasePath` | `"./assets/"` | Relative path to the Eureka assets directory |
| `iconSVG` | `"./img/icons.svg"` | Path, relative to `assetsBasePath`, to the Eureka icon sprite sheet |
| `callbacks` | `{close: undefined, choose: undefined}` | Object containing close and choose callbacks |
| `headers` | `{'Powered-By': 'Eureka by Markup.tips'}` | Additional request headers sent with XHR requests |
| `intervals` | `{searchBarPlaceholder: false,fetchDirectoryContents: 18000,updateSourceTree: false}` | Intervals for whether or not and how often to do things like hit the REST API for updated data or update the placeholder attribute based on the current directory listing |
| `enlargeFocusedRows` | `false` | Whether or not to enlarge thumbnails of focused rows |
| `mode` | `"table"` | Initial view mode (table, thumb, grid, list) |
| `sort` | `"name"` | Initial column to sort media items on |
| `allowFullscreen` | `true` | Whether or not the interface should offer a fullscreen button |
| `emphasisFocusedMediaItem` | `true` | Whether or not to emphasis selected media items (defaults to emphasizing the filename, only applies to table and list view modes) |
| `doDragNDrop` | `true` | Whether or not to enable drag 'n drop features |
| `allowChooseMultiple` | `true` | Whether or not to allow multiple files to be chosen |
| `allowInvertSelection` | `true` | Whether or not to allow selection of multiple items to be inverted |
| `allowDownloadMultiple` | `true` | Whether or not to allow multiple selected items to be download as a zip file |
*Please take note that when `useLocalStorage` is `true` any options manually passed in as props will take precedent.*
## 🌐 Browser Support
The server side rendering and HTML–first design patterns begin progressively enhancing a universally supported HTML layer. So basic features are supported in any browser. JavaScript support begins at IE9. Desired CSS layout requires Flexbox and is further enhanced with Grid Layout.
## 🔡 i18n
Eureka is on Crowdin. Please [contribute to our translations](https://crowdin.com/project/eureka-browser) if you are able.
## ♿️ Accessibility Proclaimer
Eureka strives for WCAG Level AA success criteria in all scenarios with some accessibility preference features leaning towards Level AAA. Please [log *any* a11y issues here](https://github.com/jpdevries/eureka/issues).
## ✅ Getting Started
We're going to use `yarn` so make sure that is installed.
```bash
npm install yarn -g
```
To fire up a testing server run the following:
```bash
git clone -b release-2.0 git://github.com/jpdevries/eureka.git
cd eureka
yarn prestart
yarn build
yarn serve # start the development server
# open http://localhost:3001 # Node server
```
To host the compiled production server run
```bash
yarn start # install, fetch sources, build
```
or
```bash
yarn prod # fire up the production server
```
The testing server hosts the `sources` and `client/build` directories along with a REST API to `GET`, `POST`, `PUT`, `DELETE` media items.
## ⚒ Development
The Eureka component is created with `create-react-app` and found in the `client` directory. There you can run React tests, build the React component, and start the development server.
Firstly, you'll need the testing server running for the REST API:
```bash
cd eureka
yarn server
```
Now, in another terminal tab:
```bash
cd client
yarn build
yarn test
yarn start
# open http://localhost:3000 # development server
```
The development server, like any other React app created with `create-react-app`, will automatically inject changes as you save changes to your source files.
## 🗄 REST API
Eureka is hungry for remote media sources. It needs a REST API to feed it JSON data.
Find docs at the [REST API wiki page](https://github.com/jpdevries/eureka/wiki/REST-API).
### 💄 Decorating Actions
Eureka's core Redux actions assume you'll be using a REST API. If REST isn't really your thing, or you need to modify the Redux actions for some other reason, you can decorate the actions Eureka will use. This is done using a Higher Order Component that wraps `EurekaMediaBrowser` and injects a `decoratedActions` property which will be applied as a shallow merge on top of the default actions. Reference this [Gist example of decorating actions](https://gist.github.com/jpdevries/e967056bd31cf6f01df0e431df68283b) for an example.
## 📠 Server Side Rendering
Eureka is progressively enhanced with React to be asynchronous and a richer experience in capable browsers that successfully execute scripts. But Eureka's support doesn't end at modern browsers because its design process doesn't start there. Eureka is a semantic and synchronous HTML form before it is an enhanced Virtual DOM.
Reference the [Server Side Rendering Wiki page](https://github.com/jpdevries/eureka/wiki/Server-Side-Rendering) for documentations and examples on achieving world wide support.
### ⌨️ Keyboard Shortcuts
Eureka uses JavaScript events to enrich the user experience of keyboard users.
| Shortcut | Command |
| --------------- |:-------------: |
| Toggle Sidebar | ctrl+; |
| Change View | ctrl+alt+(1-5) |
| Change Media Source | alt+(1-9) |
| Delete Item | backspace |
| Expand Item | spacebar |
| Choose Item | return |
| Create Directory | ctrl+n |
| Create file | ctrl+shift+n |
| Upload Files | ctrl+u |
| Rename Item | ctrl+r |
| Filter Items | ctrl+f |
| Sort Ascending | alt+up |
| Sort Descending | alt+down |
| Sort by filename | alt+n |
| Sort by dimensions | alt+d |
| Sort by file size | alt+f |
| Sort by edited on | alt+e |
| Set Choose Mode to Single | alt+s |
| Set Choose Mode to Multiple | alt+m |
| Invert Selection | alt+i |
## 🎨 Theming
Request additional theming options and share your themes by [opening an issue](https://github.com/jpdevries/eureka/issues/new) or [joining the discussion on Gitter](https://gitter.im/jpdevries/eureka?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge).
| Variable | Description |
| ------------- | -----|
| `--active` | Color used to highlight activated components such as the drop area |
| `--border-width` | Generic border width for panels, components, inputs |
| `--border-style` | Generic border style for panels, components, inputs |
| `--border-color` | Generic border color for panels, components, inputs |
| `--button-bg` | Background color of button elements |
| `--button-color` | Color of button text |
| `--color` | Default text color |
| `--dangerous` | Color to use for warnings and errors |
| `--light-bg` | Generic light background color, used for panels |
| `--link-color` | Default anchor text color |
| `--panel-border-color` | Border color of panel components |
| `--subtle` | Subtle color, used for Media Source Panel |
| `--very-subtle` | Very subtle color, used for drop zone area |
| `--very-subtle-icon-opacity` | Opacity for very subtle icons |
## 📣 Audible Interface
Eureka uses a combination of ARIA attributes and `.visually-hidden` text to offer an experience that is as accessible visually as it is audibly.
There is one Achilles heel here. Depending on your media source API, you might not be able to provide alternative text for images and media items. In the event that no alt text is provided, Eureka will to the best it can. For example:
> schildpad.jpg displays at 336x125, weighs 37 KB, and was edited on Sunday, April 02, 2017, Central European Summer Time
## 📺 Fullscreen Mode
To maximize usability Eureka leverages the Fullscreen API.
See the Fullscreen Mode in action
## 🏞 Masonry Layout
Eureka is enhanced by a Masonry Layout mode.
Masonry Layout Mode
If you are using Eureka as a UMD Module (probably not) you'll need [to load Masonry first](https://github.com/jpdevries/eureka/wiki/Loading-Patterns-(WIP)). If you would not like Masonry to be included in your bundle, add Masonry to your Webpack excludes. Eureka will only enable the Masonry Layout if Masonry is available.
```js
externals: {
"react": "React",
"react-dom":"ReactDOM",
"redux":"Redux",
"react-redux":"ReactRedux",
"react-masonry-component":"Masonry"
}
```
## 👀 Accessible Themes
Eureka is empowered by themes which make it more accessible to users with particular physical or contextual disabilities or preferences.
### Black on White
### White on Black
