eureka-browser v0.0.130

Eureka 🌲

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. As to be found in Redactor 3.0 for MODX by modmore. Contributions welcomed.

With eureka.js users will be saying "I found it!" in no time.   — @mrktps

💬 Discuss

Join the conversation in our public Gitter chat room.

📚 Wiki

Don't forget to browse the Wiki for more information on the REST API, patterns, screenshots and more.

🍻 Support

The Eureka Media Browser and supporting resources are provided free as in beer.
Gratuities are accepted through Square Cash.

🏋️‍♀️ Weigh In

The Eureka Media Browser is pretty lightweight all things considered.

📄 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.

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
• 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.

🛠 Usage

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.

npm install -g bower

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 <EurekaMediaBrowser> 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.

<link rel="stylesheet" type="text/css" media="screen" href="bower_components/eureka-browser/client/build/assets/css/eureka.0.0.20.min.css">

<div id="eureka-root">
  <!-- for performance, optimization, and accessibility it best to support server-side rendering by initially delivering a base HTML layer
  see server-side rendering below -->
</div>

JS

import React from 'react';
import ReactDOM from 'react-dom';
import { EurekaMediaBrowser } from 'eureka-browser';

ReactDOM.render(
  <EurekaMediaBrowser />,
  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:

  <EurekaMediaBrowser
    basePath="/"
    allowUploads={true}
    treeHidden={true}
    useLocalStorage={true}
    storagePrefix="eureka__"
    allowRename={true}
    allowDelete={true}
    confirmBeforeDelete={false}
    locale="en-US"
    mediaSource="0"
    currentDirectory="/"
    headers={{
        'Powered-By': 'Eureka by Markup.tips'
    }}
    intervals={{
      searchBarPlaceholder: false,
      fetchDirectoryContents: 18000,
      updateSourceTree: false
    }}
  />

⚙️ Options

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 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.

✅ Getting Started

We're going to use yarn so make sure that is installed.

npm install yarn -g

To fire up a testing server run the following:

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

yarn start # install, fetch sources, build

or

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:

cd eureka
yarn server

Now, in another terminal tab:

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.

💄 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 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 for documentations and examples on achieving world wide support.

⌨️ Keyboard Shortcuts

Eureka uses JavaScript events to enrich the user experience of keyboard users.

🎨 Theming

Request additional theming options and share your themes by opening an issue or joining the discussion on Gitter.

📣 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.

🏞 Masonry Layout

Eureka is enhanced by a Masonry Layout mode.

If you are using Eureka as a UMD Module (probably not) you'll need to load Masonry first. 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.

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